NORM Developer’s Guide

This document describes an application programming interface (API) for the Nack-Oriented Reliable Multicast (NORM) protocol implementation developed by the United States Naval Research Laboratory (NRL). The NORM protocol provides general purpose reliable data transport for applications wishing to use Internet Protocol (IP) Multicast services for group data delivery. NORM can also support unicast (point-to-point) data communication and may be used for such when deemed appropriate. The current NORM protocol specification is given in the Internet Engineering Task Force RFC 3940.

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.

Overview

API Initialization

Session Creation and Control

NORM Data Transport

NORM Data Transmission

NORM Data Reception

API Event Notification

API Reference

API Variable Types and Constants

NormObjectTransportId

NormEventType

NormEvent

API Initialization and Operation

NormCreateInstance()

NormDestroyInstance()

NormSetCacheDirectory()

NormGetNextEvent()

NormGetDescriptor()

Session Creation and Control

NormSetMulticastInterface()

NormSetTTL()

NormSetTOS()

NormSetLoopback()

NORM Sender Functions

NormStartSender()

NormStopSender()

NormSetTransmitRate()

NormSetTxSocketBuffer()

NormSetCongestionControl()

NormSetTransmitRateBounds()

NormSetAutoParity()

NormSetGrttEstimate()

NormAddAckingNode()

NormRemoveAckingNode()

NormStreamSetAutoFlush()

NormStreamSetPushEnable()

NormStreamMarkEom()

NormSetWatermark()

NORM Receiver Functions

NormStartReceiver()

NormStopReceiver()

NormSetRxSocketBuffer()

NormSetSilentReceiver()

NormSetDefaultUnicastNack()

NormNodeSetUnicastNack()

NormSetDefaultNackingMode()

NormNodeSetNackingMode()

NormObjectSetNackingMode()

NormSetDefaultRepairBoundary()

NormNodeSetRepairBoundary()

NormStreamRead()

NormStreamSeekMsgStart()

NormStreamGetReadOffset()

NORM Object Functions

NormObjectGetType()

NormObjectHasInfo()

NormObjectGetInfoLength()

NormObjectGetSender()

NORM Node Functions

NormNodeGetId()

NormNodeRetain()

NormNodeRelease()

Overview

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 (NormSessions). Subsequently, NORM data transmission (NormSender) operation can be activated and the application can queue various types of data (NormObjects) for reliable transport. Additionally or alternatively, NORM reception (NormReceiver) operation can also be enabled on a per-session basis and the protocol implementation alerts the application of receive events.

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

The NORM API operation can be roughly summarized with the following categories of functions:

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.

API Initialization

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 (NOTE: This limitation may change in the future. The current implementation is theoretically safe for concurrent access, but this has not been fully tested). 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.

Session Creation and Control

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.

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

NORM Data Transport

The NORM protocol supports transport of three basic types of data content. These include the types NORM_OBJECT_FILE and NORM_OBJECT_DATA 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 NORM_OBJECT_FILE type directly from/to file storage, while application memory space is accessed for the NORM_OBJECT_DATA type. The third data content type, NORM_OBJECT_STREAM, 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.

NORM Data Transmission

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.

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.

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.

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.

NORM Data Reception

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.

API Event Notification

An asynchronous event dispatching mechanism is provided to notify the application of significant NORM protocol events ...

API Reference

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

API Variable Types and Constants

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.

NormInstanceHandle

The NormInstanceHandle type is returned when a NORM API instance is created (see NormCreateInstance()). 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 NORM_INSTANCE_INVALID corresponds to an invalid API instance.

NormSessionHandle

The NormSessionHandle type is used to reference NORM transport sessions which have been created using the NormCreateSession() API call. Multiple NormSessionHandles may be associated with a given NormInstanceHandle. The special value NORM_SESSION_INVALID is used to refer to invalid session references.

NormNodeHandle

The NormNodeHandle type is used to reference state kept by the NORM implementation with respect to other participants within a NormSession. Most typically, the NormNodeHandle is used by receiver applications to dereference information about remote senders of data as needed. The special value NORM_NODE_INVALID corresponds to an invalid reference.

NormNodeId

The NormNodeId type corresponds to a 32-bit numeric value which should uniquely identify a participant (node) in a given NormSession. The NormNodeGetId() function can be used to retrieve this value given a valid NormNodeHandle. The special value NORM_NODE_NONE corresponds to an invalid (or null) node while the value NORM_NODE_ANY serves as a wildcard value for some functions.

NormObjectHandle

The NormObjectHandle 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 NormObjectHandle (see NormObjectRetain()) if needed. For sender objects, unless explicitly retained, the NormObjectHandle can be considered valid until the referenced object is explicitly canceled (see NormObjectCancel()) or purged from the sender transmission queue (see the event NORM_TX_OBJECT_PURGED). For receiver objects, these handles should be treated as valid only until a subsequent call to NormGetNextEvent() unless, again, specifically retained. The special value NORM_OBJECT_INVALID corresponds to an invalid transport object reference.

NormObjectType

The NormObjectType type is an enumeration of possible NORM data transport object types. As previously mentioned, valid types include:

Given a NormObjectHandle, the application may determine an object's type using the NormObjectGetType() function call. A special NormObjectType value, NORM_OBJECT_NONE, indicates an invalid object type.

NormObjectTransportId

The NormObjectTransportId type is a 16-bit numerical value assigned to NormObjects by senders during active transport. These values are temporarily unique with respect to a given sender within a NormSession 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 NormObjectGetTransportId() is provided to retrieve these values if needed. (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?)

NormEventType

The NormEventType 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 NormEventType values and their interpretation is given below. The function call NormGetNextEvent() is used to retrieve events from the NORM protocol engine.

NormEvent

The NormEvent type is a structure used to describe significant NORM protocol events. This structure is defined as follows:

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

API Initialization and Operation

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 NormSessions may be managed under a single NORM API instance.

NormCreateInstance()

Synopsis

Description

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 NormInstanceHandle value may be used in subsequent API calls as needed, such NormCreateSesssion(), etc. The optional priorityBoost parameter, when set to a value of true, specifies that the NORM protocol engine thread be run with higher priority scheduling. On Win32 platforms, this corresponds to THREAD_PRIORITY_TIME_CRITICAL and on Unix systems with the sched_setscheduler() API, an attempt to get the maximum allowed SCHED_FIFO priority is made. The use of this option should be carefully evaluated since, depending upon the application's scheduling priority and NORM API usage, this may have adverse effects instead of a guaranteed performance increase!

Return Values

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

NormDestroyInstance()

Synopsis

Description

The NormDestroyInstance() function immediately shuts down and destroys the NORM protocol engine instance referred to by the instance parameter. The application should make no subsequent references to the indicated NormInstanceHandle 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 NormObjectRetain() and NormObjectRelease()).

Return Values

NormSetCacheDirectory()

Synopsis

Description

This function sets the directory path used by receivers to cache newly-received NORM_OBJECT_FILE objects. This function must be called before any file objects may be received and thus should be called before any calls to NormStartReceiver() 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 NormFileRename() function may be used to rename, and thus potentially move, received files after reception has begun.

The instance parameter specifies the NORM protocol engine instance (all NormSessions associated with that instance share the same cache path) and the cachePath is a string specifying a valid (and writable) directory path. The function returns true on success and false on failure. The failure conditions are that the indicated directory does not exist or the process does not have permissions to write.

NormGetNextEvent()

Synopsis

Description

This function retrieves the next available NORM protocol event from the protocol engine. The instance parameter specifies the applicable NORM protocol engine, and the theEvent parameter must be a valid pointer to a NormEvent 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.

Note that this is currently the only blocking call in the NORM API. But non-blocking operation may be achieved by using the NormGetDescriptor() function to obtain a descriptor (or HANDLE for WIN32) suitable for asynchronous input/output (I/O) notification using such system calls as select() (UNIX) or WaitForMultipleObjects() (WIN32). The descriptor is signaled when a notification event is pending and a call to NormGetNextEvent() will not block.

NORM Notification Event Types

The following table enumerates the possible NormEvent values and describes how these notifications should be interpreted as they are retrieved by the application via the NormGetNextEvent() function call.

Return Values

This function generally blocks the thread of application execution until a NormEvent is available and returns true when a NormEvent 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 false.

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 NORM_RX_OBJECT_UPDATED events if undesired)).

NormGetDescriptor()

Synopsis

Description

This function is used to retrieve a NormDescriptor (integer file descriptor (UNIX) or HANDLE (WIN32)) suitable for asynchronous I/O notification to avoid blocking calls to NormGetNextEvent(). A NormDescriptor is available for each protocol engine instance. 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 NormGetNextEvent(). Hence, a call to NormGetNextEvent() will not block when the descriptor has been signaled. The select() system call (UNIX) (or WaitForMultipleObjects() (WIN32)) can be used to detect when the returned NormDescriptor is signaled. For the select() call usage, the NORM descriptor should be treated as a "read" descriptor.

Return Values

A descriptor is returned which is valid until a call to NormDestroyInstance() is made. Upon error, a value of NORM_DESCRIPTOR_INVALID is returned.

Session Creation and Control

NormCreateSession()

Synopsis

NormSessionHandle NormCreateSession(NormInstanceHandle instance,
                                    const char*        address,
                                    unsigned short     port,
                                    NormNodeId         localId);

Description

This function creates a NORM reliable multicast session (NormSession) using the address parameters provided. While session state is allocated and initialized, active session participation does not begin until a call is made to NormStartSender() and/or NormStartReceiver() to join the specified multicast group (if applicable) and start protocol operation. The following parameters are required in this function call:

Return Values

The returned NormSessionHandle value is valid until a call to NormDestroySession() is made. A value of NORM_SESSION_INVALID is returned upon error.

NormDestroySession()

Synopsis

Description

This function immediately terminates the application's participation in the NormSession identified by the session parameter and frees any resources used by that session. An exception to this is that the application is responsible for releasing any explicitly retained NormObjectHandles (See NormObjectRetain() and NormObjectRelease()).

Return Values

NormSetUserData()

Synopsis

Description

This function allows the application to attach a value to the previously-created NormSession instance specified by the session parameter. This value is not used or interpreted by NORM, but is available to the application for use at the programmer's discretion. The set userData value can be later retrieved using the NormGetUserData() function call.

Return Values

NormGetUserData()

Synopsis

Description

This function retrieves the "user data" value set for the specified session with a prior call to NormSetUserData().

Return Values

This function returns the user data value set for the specified session. If no user data value has been previously set a NULL (i.e., (const void*)0) value is returned.

NormGetLocalNodeId()

Synopsis

Description

This function retrieves the NormNodeId value used for the application's participation in the NormSession identified by the session parameter. The value may have been explicitly set during the NormCreateSession() call or derived using the host computer's "default" IP network address.

Return Values

The returned value indicates the NormNode identifier used by the NORM protocol engine for the local application's participation in the specified NormSession.

NormSetTxPort()

Synopsis

Description

This function is used to force NORM to use a specific port number for UDP packets sent for the specified session. By default, NORM uses separate port numbers for packet transmission and session packet reception (the receive port is specified as part of the NormCreateSession() call), allowing the operating system to pick a freely available port for transmission. This call allows the application to pick a specific port number for transmission, and furthermore allows the application to even specify the same port number for transmission as is used for reception. However, the use of separate transmit/receive ports allows NORM to discriminate when unicast feedback is occurring and thus it is not generally recommended that the transmit port be set to the same value as the session receive port. This call must be made before any calls to NormStartSender() or NormStartReceiver() to succeed.

Return Values

NormSetMulticastInterface()

Synopsis

bool NormSetMulticastInterface(NormSessionHandle session,
const char* interfaceName);

Description

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

NormSetMulticastInterface(session, "interface1");
NormStartReceiver(session, ...);
NormSetMulticastInterface(session, "interface2");

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

Return Values

A return value of true indicates success while a return value of false indicates that the specified interface was valid. This function will always return true if made before calls to NormStartSender() or NormStartReceiver(). However, those calls may fail if an invalid interface is specified.

NormSetTTL()

Synopsis

Description

This function specifies the time-to-live (ttl) for IP Multicast datagrams generated by NORM for the specified session. 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.

Return Values

A return value of true indicates success while a return value of false indicates that the specified ttl could not be set. This function will always return true if made before calls to NormStartSender() or NormStartReceiver(). However, those calls may fail if the desired ttl value cannot be set..

NormSetTOS()

Synopsis

Description

This function specifies the type-of-service (tos) field value used in IP Multicast datagrams generated by NORM for the specified session. 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.

Return Values

A return value of true indicates success while a return value of false indicates that the specified tos could not be set. This function will always return true if made before calls to NormStartSender() or NormStartReceiver(). However, those calls may fail if the desired tos value cannot be set..

NormSetLoopback()

Synopsis

Description

This function enables or disables loopback operation for the indicated NORM session. If loopbackEnable is set to true, 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 loopbackEnable is false, the application is prevented from receiving its own NORM message transmissions. By default, loopback operation is disabled when a NormSession is created.

Return Values

NORM Sender Functions

NormStartSender()

Synopsis

bool NormStartSender(NormSessionHandle session
                     unsigned long     bufferSpace
                     unsigned short    segmentSize,
                     unsigned char     blockSize,
                     unsigned char     numParity);

Description

The application's participation as a sender within a specified NormSession 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 NormEvents. The parameters required for this function call include:

These parameters are currently immutable with respect to a sender's participation within a NormSession. Sender operation must be stopped (see NormStopSender()) and restarted with another call to NormStartSender() 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 "sessionId" field may possibly be leveraged to permit a node to establish multiple virtual presences as a sender within a NormSession 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 NormSession. Again, this extended functionality is not yet supported in this implementation.

Return Values

A value of true is returned upon success and false 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. (TBD – Provide a NormGetError(NormSessionHandle session) function to retrieve a more specific error indication for this and other functions.)

NormStopSender()

Synopsis

Description

This function terminates the application's participation in a NormSession 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 NormEvent, NORM_LOCAL_SERVER_CLOSED, is dispatched when the graceful shutdown process has completed.

(NOTE: The "graceful" parameter is currently not available, and the current behavior of this API call corresponds to the default behavior of graceful = false). The functionality described here will soon be supported in the API.

Return Values

NormSetTransmitRate()

Synopsis

Description

This function sets the transmission rate limit (in bits per second (bps)) used for NormSender transmissions. For fixed-rate transmission of NORM_OBJECT_FILE or NORM_OBJECT_DATA, this limit determines the data rate at which NORM protocol messages and data content. For NORM_OBJECT_STREAM 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 NormSetCongestionControl()), the rate set here will be set, but congestion control operation may quickly readjust the rate unless disabled.

Return Values

NormSetTxSocketBuffer()

Synopsis

Description

This function can be used to set a non-default socket buffer size for the UDP socket used by the specified NORM session for data transmission. The bufferSize parameter specifies the desired socket buffer size in bytes. Large transmit socket buffer sizes may be necessary to achieve high throughput rates when NORM, as a user-space process, is unable to precisely time its packet transmissions. Similarly, NORM receivers may need to set large receive socket buffer sizes to achieve sustained high data rate reception (see NormSetRxSocketBuffer()).

Return Values

This function returns true upon success and false upon failure. Possible failure modes include an invalid session parameter, a call to NormStartReceiver() or NormStartSender() has not yet been made for the session, or an invalid bufferSize was given. Note some operating systems may require additional configuration to use non-standard socket buffer sizes.

NormSetCongestionControl()

Synopsis

Description

This function enables (or disables) the NORM sender congestion control operation for the session designated by the session parameter. For best operation, this function should be called before the call to NormStartSender() is made, but congestion control operation can be dynamically enabled/disabled during the course of sender operation. If the value of enable is true, congestion control operation is enabled while it is disabled for enable equal to false. 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 NormSetTransmitRateBounds()) the rate adjustment will remain within any set bounds. The rate set by NormSetTransmitRate() 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.

Return Values

NormSetTransmitRateBounds()

Synopsis

bool NormSetTransmitRateBounds(NormSessionHandle session,
double rateMin,
double rateMax);

Description

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 rateMin corresponds to the minimum transmission rate (bps) and rateMax 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 "NormSetTransmitRate(session, -1.0, 64000.0)" 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 NormSetCongestionControl()). If the current congestion control rate falls outside of the specified bounds, the sender transmission rate will

Return Values

This function returns true upon success. If both rateMin and rateMax are greater than or equal to zero, but (rateMax < rateMin), the rate bounds will remain unset or unchanged and the function will return false.

NormSetAutoParity()

Synopsis

void NormSetAutoParity(NormSessionHandle sessionHandle,
unsigned char autoParity);

Description

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., autoParity = 0), FEC content is sent only in response to repair requests (NACKs) from receivers. But, by setting a non-zero value for autoParity, 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 blockSize parameter used when NormStartSender() was called for the given sessionHandle.

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.

The value of autoParity set must be less than or equal to the numParity parameter set when NormStartSender() was called for the given sessionHandle.

Return Values

NormSetGrttEstimate()

Synopsis

Description

This function sets the sender's estimate of group round-trip timing (GRTT). This function is expected to most typically used to initialize the sender's GRTT estimate prior to the call to NormStartSender() when the application has a priori confidence that the default initial GRTT value of 0.5 second is inappropriate. The sender GRTT estimate will be updated during normal sender protocol operation after sender startup or if this call is made while sender operation is active. For experimental purposes (or very special application needs), this API provides a mechanism to control or disable the sender GRTT update process (see NormSetGrttProbing()). The grtt value will be limited to the maximum GRTT as set (see NormSetGrttMax()) or the default maximum of 10 seconds.

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

Return Values

NormAddAckingNode()

Synopsis

Description

When this function is called, the specified nodeId is added to the list of NormNodes used when NORM sender operation performs positive acknowledgement (ACK) collection for the specified session. The optional NORM positive acknowledgement collection occurs when a specified transmission point (see NormSetWatermark()) is reached or for specialized protocol actions such as positively-acknowledged application-defined commands (TBD).

Return Values

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

NormRemoveAckingNode()

Synopsis

Description

This function deletes the specified nodeId from the list of NormNodes used when NORM sender operation performs positive acknowledgement (ACK) collection for the specified session.

Return Values

NormFileEnqueue()

Synopsis

NormObjectHandle NormFileEnqueue(NormSessionHandle session,
                                 const char*       filename,
                                 const char*       infoPtr = NULL,
                                 unsigned int      infoLen = 0);

Description

This function enqueues a file for transmission within the specified NORM session. Note that NormStartSender() must have been previously called before files or any transport objects may be enqueued and transmitted. The fileName 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 infoPtr and infoLen parameters are used to associate NORM_INFO content with the sent transport object. The maximum allowed infoLen corresponds to the segmentSize used in the prior call to NormStartSender(). The use and interpretation of the NORM_INFO content is left to the application's discretion. Example usage of NORM_INFO content for NORM_OBJECT_FILE 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.

The application is allowed to enqueue multiple transmit objects within in the "transmit cache" limits (see NormSetTxCacheLimits()) and enqueued objects are transmitted (and repaired as needed) within the limits determined by automated congestion control (see NormSetCongestionControl()) or fixed rate (see NormSetTxRate()) parameters.

Return Values

A NormObjectHandle 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 NormObjectCancel()) or a NORM_TX_OBJECT_PURGED event is received for the given object. Note the application may use the NormObjectRetain() method if it wishes to refer to the object after the NORM_TX_OBJECT_PURGED notification. In this case, the application, when finished with the object, must use NormObjectRelease() to free any resources used or else a memory leak condition will result. A value of NORM_OBJECT_INVALID is return upon error. Possible failure conditions include the specified session is not operating as a NormSender, insufficient memory resources were available, or the "transmit cache" limits have been reached and all previously enqueued NORM transmit objects are pending transmission. Also the call will fail if the infoLen parameter exceeds the local NormSender segmentSize limit.

NormDataEnqueue()

Synopsis

NormObjectHandle NormDataEnqueue(NormSessionHandle session,
                                 const char*       dataPtr,
                                 unsigned int      dataLen,
                                 const char*       infoPtr = NULL,
                                 unsigned int      infoLen = 0);

Description

This function enqueues a segment of application memory space for transmission within the specified NORM session. Note that NormStartSender() must have been previously called before files or any transport objects may be enqueued and transmitted. The dataPtr parameter must be a valid pointer to the area of application memory to be transmitted and the dataLen 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 infoPtr and infoLen parameters are used to associate NORM_INFO content with the sent transport object. The maximum allowed infoLen corresponds to the segmentSize used in the prior call to NormStartSender(). The use and interpretation of the NORM_INFO content is left to the application's discretion. Example usage of NORM_INFO content for NORM_OBJECT_DATA 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.

Return Values

A NormObjectHandle 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 NormObjectCancel()) or a NORM_TX_OBJECT_PURGED event is received for the given object. Note the application may use the NormObjectRetain() method if it wishes to refer to the object after the NORM_TX_OBJECT_PURGED notification. In this case, the application, when finished with the object, must use NormObjectRelease() to free any resources used or else a memory leak condition will result. A value of NORM_OBJECT_INVALID is return upon error. Possible failure conditions include the specified session is not operating as a NormSender, insufficient memory resources were available, or the "transmit cache" limits have been reached and all previously enqueued NORM transmit objects are pending transmission. Also the call will fail if the infoLen parameter exceeds the local NormSender segmentSize limit.

NormStreamOpen()

Synopsis

NormObjectHandle NormStreamOpen(NormSessionHandle session,
                                unsigned int      bufferSize,
                                const char*       infoPtr = NULL,
                                unsigned int      infoLen = 0);

Description

This function opens a NORM_OBJECT_STREAM sender object and enqueues it for transmission within the indicated session. 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 NormStreamWrite() are made unless NORM_INFO content is specified for the stream with the infoPtr and infoLen parameters. Example usage of NORM_INFO content for NORM_OBJECT_STREAM 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 bufferSize parameter controls the size of the stream's "repair window" which limits how far back the sender will "rewind" to satisfy receiver repair requests.

NORM, as a NACK-oriented protocol, currently lacks a mechanism for receivers to explicitly feedback flow control status to the sender unless the sender leverages NORM's optional positive acknowledgement (ACK) features. Thus, the bufferSize selection plays an important role in NORM's reliability. Generally, a larger bufferSize 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 bufferSize 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 NormStreamMarkEom()).

Note that the current implementation of NORM is designed to support only one active stream per session, and that any NORM_OBJECT_DATA or NORM_OBJECT_FILE 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 NormSessions as needed.

Note there is no corresponding "open" call for receiver streams. Receiver NORM_OBJECT_STREAMs are automatically opened by the NORM protocol engine and the receiver applications is notified of new streams via the NORM_RX_OBJECT_NEW notification (see NormGetNextEvent()).

Return Values

A NormObjectHandle 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 NormObjectCancel()) or a NORM_TX_OBJECT_PURGED event is received for the given object. Note the application may use the NormObjectRetain() method if it wishes to refer to the object after the NORM_TX_OBJECT_PURGED notification. In this case, the application, when finished with the object, must use NormObjectRelease() to free any resources used or else a memory leak condition will result. A value of NORM_OBJECT_INVALID is return upon error. Possible failure conditions include the specified session is not operating as a NormSender, insufficient memory resources were available, or the "transmit cache" limits have been reached and all previously enqueued NORM transmit objects are pending transmission. Also the call will fail if the infoLen parameter exceeds the local NormSender segmentSize limit.

NormStreamClose()

Synopsis

Description

This function halts transfer of the stream specified by the streamHandle parameter and releases any resources used unless the associated object has been explicitly retained by a call to NormObjectRetain(). This function is equivalent to the NormObjectCancel() routine and may be used for sender or receiver streams. This alternative function is simply provided to compliment the NormStreamOpen() call.

Return Values

NormStreamWrite()

Synopsis

unsigned int NormStreamWrite(NormObjectHandle streamHandle
const char* buffer,
unsigned int numBytes);

Description

This function enqueues data for transmission within the NORM stream specified by the streamHandle parameter. The buffer parameter must be a pointer to the data to be enqueued and the numBytes parameter indicates the length of the data content. Note this call does not block and will return immediately. The return value indicates the number of bytes copied from the provided buffer to the internal stream transmission buffers. Calls to this function will be successful unless the stream's transmit buffer space is fully occupied with data pending original or repair transmission if the stream's "push mode" is set to false (default, see NormStreamSetPushMode() for details). If the stream's "push mode" is set to true, a call to NormStreamWrite() 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.

Return Values

This function returns the number of bytes of data successfully enqueued for NORM stream transmission.

NormStreamFlush()

Synopsis

void NormStreamFlush(NormObjectHandle streamHandle,
bool eom = false,
NormFlushMode flushMode = NORM_FLUSH_PASSIVE);

Description

This function causes an immediate "flush" of the transmit stream specified by the streamHandle parameter. Normally, unless NormSetAutoFlush() 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 segmentSize parameter of the NormStartSender() 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 NormStreamFlush() for flushMode equal to NORM_FLUSH_PASSIVE 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 flushMode parameter is set to NORM_FLUSH_ACTIV, the application can achieve reliable delivery of stream content up to the current write position in an even more proactive fashion. In this case, the sender additionally, actively transmits 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 flushMode is set to NORM_FLUSH_NONE, this call has no effect other than the optional end-of-message marking described here.

The optional eom parameter, when set to true, allows the sender application to mark an end-of-message indication (see NormStreamMarkEom()) 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.

Note that frequent flushing, particularly for NORM_FLUSH_ACTIVE 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.

Return Values

NormStreamSetAutoFlush()

Synopsis

void NormStreamSetAutoFlush(NormObjectHandle streamHandle
NormFlushMode flushMode);

Description

This function sets "automated flushing" for the NORM transmit stream indicated by the streamHandle parameter. By default, a NORM transmit stream is "flushed" only when explicitly requested by the application (see NormStreamFlush()). However, to simplify programming, the NORM API allows that automated flushing be enabled such that the "flush" operation occurs every time the full requested buffer provided to a NormStreamWrite() 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.

Possible values for the flushMode parameter include NORM_FLUSH_NONE, NORM_FLUSH_PASSIVE, and NORM_FLUSH_ACTIVE. The default setting for a NORM stream is NORM_FLUSH_NONE where no flushing occurs unless explicitly requested via NormStreamFlush(). By setting the automated flushMode to NORM_FLUSH_PASSIVE, 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 NormSender segmentSize parameter) are generated as a result. If NORM_FLUSH_ACTIVE 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.

Return Values

NormStreamSetPushEnable()

Synopsis

Description

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 NormStreamWrite() will return a zero value under this condition, indicating it was unable to enqueue the new data. However, if pushEnable is set to true for a given streamHandle, 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 NormStreamWrite() 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 pushEnable equals false. 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.

Return Values

NormStreamMarkEom()

Synopsis

Description

This function allows the application to indicate to the NORM protocol engine that the last data successfully written to the stream indicated by streamHandle corresponded to the end of an application-defined message boundary. If the stream is either explicitly flushed at this point (see NormStreamFlush()) or the last write had exactly filled a NormSender segmentSize 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.

It is recommended that the NormStreamMarkEom() should be used with automated flushing modes (see NormStreamSetAutoFlush()) while the optional eom parameter of NormStreamFlush() is instead used when explicit flushing is practiced. End-of-message marking may 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 NormSender segmentSize. Again, note future versions of NORM and this implementation may provide more flexibility here.

Return Values

NormSetWatermark()

Synopsis

Description

This function specifies a "watermark" transmission point at which NORM sender protocol operation should perform positive acknowledgment collection for a given session. For NORM_OBJECT_FILE and NORM_OBJECT_DATA transmissions, the positive acknowledgement collection will begin when the specified object has been completely transmitted. The object parameter must be a valid handle to a previously-created sender object (see NormEnqueueFile(), NormEnqueueData(), or NormStreamOpen()). For NORM_OBJECT_STREAM transmission, the positive acknowledgment collection begins immediately, using the current position (last data written) of the sender stream as a reference.

As the acknowledgment collection proceeds, NORM_ACK_FAILED events will be posted for individual receiver NormNodes which fail to acknowledge the request. The NormEvent::node field contains a NormNodeHandle for the failed node and NormNodeGetId() can be used to retrieve the failing node's NormNodeId. When the sender acknowledgment collection process has completed, the NORM_ACK_COMPLETE event is posted and the application may assume that the remaining nodes (those for which there was no NORM_ACK_FAILED event) successfully acknowledged the request.

If a subsequent call is made to NormSetWatermark() before the prior acknowledgement request has completed, the pending acknowledgment request is canceled and new one may begin.

Note that the sender may still enqueue NormObjects 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 NORM_ACK_COMPLETE event is received for the session. 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.

Return Values

The function returns true upon successful establishment of the watermark point. The function may return false upon failure (why would it fail? – TBD).

NORM Receiver Functions

NormStartReceiver()

Synopsis

Description

This function initiates the application's participation as a receiver within the NormSession identified by the session parameter. The receiver will respond with appropriate protocol messages (unless NormSetSilentReceiver(true) is invoked) and begin providing the application with receiver-related NormEvent notification. The bufferSpace parameter is used to set a limit on the amount of bufferSpace allocated by the receiver per active NormSender within the session. The appropriate bufferSpace to use is a function of expected network delay*bandwidth product and packet loss characteristics. A discussion of trade-offs associated with NORM transmit and receiver buffer space selection is provided later in this document. An insufficient bufferSpace allocation will result in potentially inefficient protocol operation, even though reliable operation may be maintained. In some cases of a large delay*bandwidth product and/or severe packet loss, a small bufferSpace 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).

Return Values

A value of true is returned upon success and false 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.

NormStopReceiver()

Synopsis

Description

This function ends the application's participation as a receiver in the NormSession specified by the session parameter. By default, all receiver-related protocol activity is immediately halted and all receiver-related resources are freed (except for those which have been specifically retained (see NormObjectRetain()). However, and optional gracePeriod parameter is provided to allow the receiver an opportunity to inform the group of its intention. This is applicable when the local receiving NormNode 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 gracePeriod 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 gracePeriod 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" = (gracePeriod * GRTT)). 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 gracePeriod expires, whichever comes first), the NORM protocol engine will post a NORM_LOCAL_RECEIVER_CLOSED event for the applicable session, and related resources are then freed.

Return Values

NormSetRxSocketBuffer()

Synopsis

Description

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

Return Values

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

NormSetSilentReceiver()

Synopsis

Description

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 session. Setting the silent parameter to true enables silent receiver operation while setting it to false 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 NormSetAutoParity()) or using repair information requested by other non-silent receivers within the group to achieve reliable transfers.

Return Values

NormSetDefaultUnicastNack()

Synopsis

Description

This function controls the default behavior determining the destination of receiver feedback messages generated while participating in the session. If state is true, "unicast NACKing" is enabled for new remote senders while it is disabled for state equal to false. The NACKing behavior for current remote senders is not affected. When "unicast NACKing" is disabled (default), NACK messages are sent to the session address (usually a multicast address) and port, but "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 NormSetWatermark()) are always unicast to the applicable sender. (TBD – provide API option so that all messages are multicast.) The default session-wide behavior for unicast NACKing can be overridden via the NormNodeSetUnicastNack() function for individual remote senders.

Return Values

NormNodeSetUnicastNack()

Synopsis

Description

This function controls the the destination address of receiver feedback messages generated in response to a specific remote NORM sender.. If state is true, "unicast NACKing" is enabled while it is disabled for state equal to false. See the description of NormSetDefaultUnicastNack() for details on 'unicast NACKing" behavior.

Return Values

NormSetDefaultNackingMode()

Synopsis

void NormSetDefaultNackingMode(NormSessionHandle session,
NormNackingMode nackingMode);

Description

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:

This function specifies the default behavior with respect to any new sender or object. This default behavior may be overridden for specific sender nodes or specific object using NormNodeSetNackingMode() or NormObjectSetNackingMode(), respectively. The receiver application's use of NORM_NACK_NONE 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 NORM_NACK_INFO_ONLY 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 NormObjectSetNackingMode() call. Similarly, the receiver may changes its default nacking mode with respect to specific senders via the NormNodeSetNackingMode() call. The default "default nacking mode" when this call is not made is NORM_NACK_NORMAL.

Return Values

NormNodeSetNackingMode()

Synopsis

void NormNodeSetNackingMode(NormNodeHandle nodeHandle,
NormNackingMode nackingMode);

Description

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

Return Values

NormObjectSetNackingMode()

Synopsis

void NormObjectSetNackingMode(NormObjectHandle objectHandle,
NormNackingMode nackingMode);

Description

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

Return Values

NormSetDefaultRepairBoundary()

Synopsis

void NormSetDefaultRepairBoundary(NormSessionHandle sessionHandle,
NormRepairBoundary repairBoundary);

Description

This function allows the receiver application to customize, for a given sessionHandle, 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 repairBoundary equal to NORM_BOUNDARY_BLOCK. Using this function, the application may alternatively, setting repairBoundary equal to NORM_BOUNDARY_OBJECT, 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 NormSetAutoParity()) 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 NormNodeSetRepairBoundary() function.

Return Values

NormNodeSetRepairBoundary()

Synopsis

void NormNodeSetRepairBoundary(NormNodeHandle nodeHandle,
NormRepairBoundary repairBoundary);

Description

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

Return Values

NormStreamRead()

Synopsis

bool NormStreamRead(NormObjectHandle streamHandle,
char* buffer
unsigned int* numBytes);

Description

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 NORM_RX_OBJECT_NEW notification events. The streamHandle parameter here must correspond to a valid NormObjectHandle value provided during such a prior NORM_RX_OBJECT_NEW notification. The buffer parameter must be a pointer to an array where the received data can be stored of a length as referenced by the numBytes pointer. On successful completion, the numBytes storage will be modified to indicate the actual number of bytes copied into the provided buffer. If the numBytes storage is modified to a zero value, this indicates that no stream data was currently available for reading.

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

Return Values

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 NormStreamSeekMsgStart() or NormStreamGetOffset() if needed to recover its alignment with received stream content. This depends upon the nature of the application and its stream content.

NormStreamSeekMsgStart()

Synopsis

Description

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

Return Values

This function returns a value of true when start-of-message is found. The next call to NormStreamRead() 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 false. In this case, the application should defer repeating a call to this function until a subsequent NORM_RX_OBJECT_UPDATE notification is posted.

NormStreamGetReadOffset()

Synopsis

Description

This function retrieves the current read offset value for the receive stream indicated by the streamHandle 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.

Return Values

This function returns the current read offset in bytes. The return value is undefined for sender streams. There is no error result.

NORM Object Functions

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 NormObjectHandle argument which specifies the applicable object. Note that NormObjectHandle values obtained from a NormEvent notification may be considered valid only until a subsequent call to NormGetNextEvent(), unless explicitly retained by the application (see NormObjectRetain()). NormObjectHandle values obtained as a result of NormFileEnqueue(), NormDataEnqueue(), or NormOpenStream() calls can be considered valid only until a corresponding NORM_TX_OBJECT_PURGED notification is posted or the object is dequeued using NormCancelObject(), unless, again, otherwise explicitly retained (see NormObjectRetain()).

NormObjectGetType()

Synopsis

Description

This function can be used to determine the object type (NORM_OBJECT_DATA, NORM_OBJECT_FILE, or NORM_OBJECT_STREAM) for the NORM transport object identified by the objectHandle parameter. The objectHandle must refer to a current, valid transport object.

Return Values

This function returns the NORM object type. Valid NORM object types include NORM_OBJECT_DATA, NORM_OBJECT_FILE, or NORM_OBJECT_STREAM. A type value of NORM_OBJECT_NONE will be returned for an objectHandle value of NORM_OBJECT_INVALID.

NormObjectHasInfo()

Synopsis

Description

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

Return Values

A value of true is returned if NORM_INFO is (or will be) available for the specified transport object. A value of false is returned otherwise.

NormObjectGetInfoLength()

Synopsis

Description

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 objectHandle parameter.

Return Values

The length of the NORM_INFO content, in bytes, of currently available for the specified transport object is returned. A value of 0 is returned if no NORM_INFO content is currently available or associated with the object.

NormObjectGetInfo()

Synopsis

unsigned short NormObjectGetInfo(NormObjectHandle objectHandle,
char* buffer,
unsigned short bufferLen);

Description

This function copies any NORM_INFO content associated (by the sender application) with the transport object specified by objectHandle into the provided memory space referenced by the buffer parameter. The bufferLen parameter indicates the length of the buffer space in bytes. If the provided bufferLen 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 NORM_RX_OBJECT_INFO 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 NormObjectHasInfo() 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).

Return Values

The actual length of currently available 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 NULL buffer value and zero bufferLen is provided. A zero value is returned if NORM_INFO content has not yet been received (or is non-existent) for the specified object.

NormObjectGetSize()

Synopsis

Description

This function can be used to determine the size (in bytes) of the transport object specified by the objectHandle parameter. NORM can support large object sizes for the NORM_OBJECT_FILE 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., "#define _FILE_OFFSET_BITS 64" or equivalent). Developers should configure their build environment to correspond with the NORM library used to ensure that the "off_t" type is appropriately defined.

For objects of type NORM_OBJECT_STREAM, the size returned here corresponds to the stream buffer size set by the sender application when opening the referenced stream object.

Return Values

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.

NormObjectCancel()

Synopsis

Description

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 objectHandle parameter. The objectHandle 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 NormObjectRetain() 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 objectHandle after this call is made.

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, will acknowledge the object as completed with respect to any associated positive acknowledgement requests (see NormSetWatermark()).

Return Values

NormObjectRetain()

Synopsis

Description

This function "retains" the objectHandle 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 NormObjectHandle 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 NORM_TX_OBJECT_PURGED notification) by the protocol engine, or, for receiver objects, from the time of the object's NORM_RX_OBJECT_NEW notification until its reception is canceled by the application or a NORM_RX_OBJECT_COMPLETED or NORM_RX_OBJECT_ABORTED 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 NormGetNextEvent().

When the application makes a call to NormObjectRetain() for a given objectHandle, the application may use that objectHandle value in any NORM API calls until the application makes a call to NormObjectRelease() for the given object. Note that the application MUST make a corresponding call to NormObjectRelease() for each call it has made to NormObjectRetain() 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 NormNodeHandle corresponding to the remote sender of that receive object so that the application may use NORM node API calls for the value returned by NormObjectGetSender() as needed.

Return Values

NormObjectRelease()

Synopsis

Description

This function complements the NormObjectRetain() call by immediately freeing any resources associated with the given objectHandle, 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 NormObjectRelease() for an objectHandle for which it has not previously explicitly retained via NormObjectRetain().

Return Values

NormFileGetName()

Synopsis

bool NormFileGetName(NormObjectHandle fileHandle)
char* nameBuffer,
unsigned int bufferLen);

Description

This function copies the name, as a NULL-terminated string, of the file object specified by the fileHandle parameter into the nameBuffer of length bufferLen bytes provided by the application. The fileHandle parameter must refer to a valid NormObjectHandle for an object of type NORM_OBJECT_FILE. If the actual name is longer than the provided bufferLen, 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 nameBuffer.

Return Values

This function returns true upon success and false upon failure. Possible failure conditions include the fileHandle does not refer to an object of type NORM_OBJECT_FILE.

NormFileRename()

Synopsis

Description

This function renames the file used to store content for the NORM_OBJECT_FILE transport object specified by the fileHandle 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 fileName 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.

Return Values

This function returns true upon success and false upon failure. Possible failure conditions include the case where the fileHandle does not refer to an object of type NORM_OBJECT_FILE and where NORM was unable to successfully create any needed directories and/or the file itself.

NormDataAccessData()

Synopsis

Description

This function allows the application to access the data storage area associated with a transport object of type NORM_OBJECT_DATA. 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 NormDataDetachData() function if it is desired to avoid the copy.

If the object specified by the objectHandle parameter has no data content (or is not of type NORM_OBJECT_DATA), a NULL value may be returned. The application MUST NOT attempt to modify the memory space used by NORM_OBJECT_DATA objects during the time an associated objectHandle is valid. The length of data storage area can be determined with a call to NormObjectGetSize() for the same objectHandle value.

Return Values

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 NORM_OBJECT_DATA.

NormDataDetachData()

Synopsis

Description

This function allows the application to disassociate data storage allocated by the NORM protocol engine for a receive object from the NORM_OBJECT_DATA transport object specified by the objectHandle parameter. It is important that this function is called after the NORM protocol engine has indicated it is finished with the data object (i.e., after a NORM_TX_OBJECT_PURGED, NORM_RX_OBJECT_COMPLETED, or NORM_RX_OBJECT_ABORTED notification event). But the application must call NormDataDetachData() before a call is made to NormObjectCancel() or NormObjectRelease() 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 NORM_OBJECT_DATA transport object is deleted and the application will be unable to access the received data unless it has previously copied the content.

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.

Return Values

NormObjectGetSender()

Synopsis

Description

This function retrieves the NormNodeHandle corresponding to the remote sender of the transport object associated with the given objectHandle parameter. Note that the returned NormNodeHandle value is only valid for the same period that the objectHandle is valid. The returned NormNodeHandle may optionally be retained for further use by the application using the NormNodeRetain() function call. The returned value can be used in the NORM Node Functions described later in this document.

Return Values

This function returns the NormNodeHandle corresponding to the remote sender of the transport object associated with the given objectHandle parameter. A value of NORM_NODE_INVALID is returned if the specified objectHandle references a locally originated, sender object.

NORM Node Functions

The functions described in this section may be used for NORM sender or receiver (most typically receiver) purposes to retrieve additional information about a NormNode, given a valid NormNodeHandle. Note that, unless specifically retained (see NormNodeRetain()), a NormNodeHandle provided in a NormEvent notification should be considered valid only until a subsequent call to NormGetNextEvent() is made. NormNodeHandles retrieved using NormObjectGetSender() can be considered valid for the same period of time as the corresponding NormObjectHandle is valid.

NormNodeGetId()

Synopsis

Description

This function retrieves the NormNodeId identifier for the remote participant referenced by the given nodeHandle value. The NormNodeId 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.

Return Values

This function returns the NormNodeId value associated with the specified nodeHandle. In the case nodeHandle is equal to NORM_NODE_INVALID, the return value will be NORM_NODE_NONE.

NormNodeRetain()

Synopsis

Description

In the same manner as the NormObjectRetain() function, this function allows the application to retain state associated with a given nodeHandle value even when the underlying NORM protocol engine might normally free the associated state and thus invalidate the NormNodeHandle. If the application uses this function, it must make a corresponding call to NormNodeRelease() when finished with the node information to avoid a memory leak condition. NormNodeHandle values (unless retained) are valid from the time of a NORM_REMOTE_SERVER_NEW notification until a complimentary NORM_REMOTE_SERVER_PURGED notification. During that interval, the application will receive NORM_REMOTE_SERVER_ACTIVE and NORM_REMOTE_SERVER_INACTIVE notifications according to the server's message transmission activity within the session.

It is important to note that, if the NORM protocol engine posts a NORM_REMOTE_SERVER_PURGED notification for a given NormNodeHandle, the NORM protocol engine could possibly, subsequently establish a new, different NormNodeHandle value for the same remote server (i.e., one of equivalent NormNodeId) if it again becomes active in the session. A new NormNodeHandle may likely be established even if the application has retained the previous NormNodeHandle value. Therefore, to the application, it might appear that two different servers with the same NormNodeId 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.

Return Values

NormNodeRelease()

Synopsis

Description

In complement to the NormNodeRetain() function, this API call releases the specified nodeHandle 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 NormNodeHandle, unless it is still valid.

Sender Notification Event Types:
NORM_TX_QUEUE_VACANCY	This event indicates that there is room for additional transmit objects to be enqueued, or, if the handle of NORM_OBJECT_STREAM is given in the event "object" field, the application may successfully write to the indicated stream object.
NORM_TX_QUEUE_EMPTY	This event indicates the NORM protocol engine has no new data pending transmission and the application may enqueue additional objects for transmission.
NORM_TX_OBJECT_SENT	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.
NORM_TX_OBJECT_PURGED	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 (NormObjectHandle) is no longer valid unless it is specifically retained by the application.
NORM_LOCAL_SERVER_CLOSED	This event is posted when the NORM protocol engine completes the "graceful shutdown" of its participation as a sender in the indicated "session" (see NormStopSender()).
Receiver Notification Event Types:
NORM_REMOTE_SERVER_NEW	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 (NormNodeHandle).
NORM_REMOTE_SERVER_ACTIVE	This event is posted when a previously inactive (or new) remote server is detected operating as an active sender within the session.
NORM_REMOTE_SERVER_INACTIVE	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.
NORM_REMOTE_SERVER_PURGED	This event is posted when the NORM protocol engine frees resources for, and thus invalidates the indicated "node" handle.
NORM_RX_OBJECT_NEW	This event is posted when reception of a new transport object begins and marks the beginning of the interval during which the specified "object" (NormObjectHandle) is valid.
NORM_RX_OBJECT_INFO	This notification is posted when the NORM_INFO content for the indicated "object" is received.
NORM_RX_OBJECT_UPDATED	This event indicates that the identified receive "object" has newly received data content.
NORM_RX_OBJECT_COMPLETED	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 NormObjectHandle becomes invalid and must no longer be referenced.
NORM_RX_OBJECT_ABORTED	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 NormObjectHandle becomes invalid and must no longer be referenced.
Miscellaneous Notification Event Types
NORM_EVENT_INVALID	This NormEventType indicates an invalid or "null" notification which should be ignored.

instance	This must be a valid NormInstanceHandle previously obtained with a call to NormCreateInstance().
address	This points to a string containing an IP address (e.g. dotted decimal IPv4 address (or IPv6 address) or name resolvable to a valid IP address. The specified address (along with the port number) determines the destination of NORM messages sent. For multicast sessions, NORM senders and receivers must use a common multicast address and port number. For unicast sessions, the sender and receiver must use a common port number, but specify the other node's IP address as the session address (Although note that receiver-only unicast nodes who are providing unicast feedback to senders will not generate any messages to the session IP address and the address parameter value is thus inconsequential for this special case).
port	This must be a valid, unused port number corresponding to the desired NORM session address. See the address parameter description for more details.
localId	The localId parameter specifies the NormNodeId that should be used to identify the application's presence in the NormSession. All participant's in a NormSession should use unique localId values. The application may specify a value of NORM_NODE_ANY or NORM_NODE_ANY for the localId 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 NormNodeId collisions. Thus, the application should explicitly specify the localId unless there is a high degree of confidence that the default IP address will provide a unique identifier.

session	This must be a valid NormSessionHandle previously obtained with a call to NormCreateSession().
bufferSpace	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 bufferSpace value is function of the network topology bandwidthdelay* product and packet loss characteristics. If the bufferSpace 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 bufferSpace allocation is safer at the expense of possibly committing more memory resources.
segmentSize	This parameter sets the maximum payload size (in bytes) of NORM sender messages (not including any NORM message header fields). A sender's segmentSize 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 NormSession may use different segmentSize values. Generally, the appropriate segment size to use is dependent upon the types of networks forming the multicast topology, but applications may choose different values for other purposes. Note that application designers MUST account for the size of NORM message headers when selecting a segmentSize. For example, the NORM_DATA message header for a NORM_OBJECT_STREAM 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 + segmentSize) bytes.
blockSize	This parameter sets the number of source symbol segments (packets) per coding block, for the systematic Reed-Solomon FEC code used in the current NORM implementation. For traditional systematic block code "(n,k)" nomenclature, the blockSize value corresponds to "k". NORM logically segments transport object data content into coding blocks and the blockSize parameter determines the number of source symbol segments (packets) comprising a single coding block where each source symbol segment is up to segmentSize bytes in length.. A given block's parity symbol segments are calculated using the corresponding set of source symbol segments. The maximum blockSize allowed by the 8-bit Reed-Solomon codes in NORM is 255, with the further limitation that (blockSize + numParity) ≤ 255.
numParity	This parameter sets the maximum number of parity symbol segments (packets) the sender is willing to calculate per FEC coding block. The parity symbol segments for a block are calculated from the corresponding blockSize source symbol segments. In the "(n,k)" nomenclature mention above, the numParity value corresponds to "n-k". 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 blockSize, the maximum numParity value is (255 – blockSize). However, note that computational complexity increases significantly with increasing numParity values and applications may wish to be conservative with respect to numParity 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.

NORM_NACK_NONE	Do not transmit any repair requests for the newly received object.
NORM_NACK_INFO_ONLY	Transmit repair requests for NORM_INFO content only as needed.
NORM_NACK_NORMAL	Transmit repair requests for entire object as needed.

Background

Contents

Overview

API Initialization

Session Creation and Control

NORM Data Transport

NORM Data Transmission

NORM Data Reception

API Event Notification

API Reference

API Variable Types and Constants

API Initialization and Operation

Synopsis

Description

Return Values

Synopsis

Description

Return Values

Synopsis

Description

Synopsis

Description

NORM Notification Event Types

Return Values

Synopsis

Description

Return Values

Session Creation and Control

Synopsis

Description

Return Values

Synopsis

Description

Return Values

Synopsis

Description

Return Values

Synopsis

Description

Return Values

Synopsis

Description

Return Values

Synopsis

Description

Return Values

Synopsis

Description

Return Values

Synopsis

Description

Return Values

Synopsis

Description

Return Values

Synopsis

Description

Return Values

NORM Sender Functions

Synopsis

Description

Return Values

Synopsis

Description

Return Values

Synopsis

Description

Return Values

Synopsis

Description

Return Values

Synopsis

Description

Return Values

Synopsis

Description

Return Values

Synopsis

Description

Return Values