NAME

       dgr - Datagram Retransmission system library

SYNOPSIS

           #include "dgr.h"

           [see description for available functions]

DESCRIPTION

       The DGR library is an alternative implementation of a subset of LTP, intended for use over
       UDP/IP in the Internet; unlike ION's canonical LTP implementation it includes a congestion
       control mechanism that interprets LTP block transmission failure as an indication of
       network congestion (not data corruption) and reduces data transmission rate in response.

       As such, DGR differs from many reliable-UDP systems in two main ways:

               It uses adaptive timeout interval computation techniques
               borrowed from TCP to try to avoid introducing congestion
               into the network.

               It borrows the concurrent-session model of transmission
               from LTP (and ultimately from CFDP), rather than waiting
               for one datagram to be acknowledged before sending the next,
               to improve bandwidth utilization.

       At this time DGR is interoperable with other implementations of LTP only when each block
       it receives is transmitted in a single LTP data segment encapsulated in a single UDP
       datagram.  More complex LTP behavior may be implemented in the future.

       int dgr_open(uvast ownEngineId, unsigned in clientSvcId, unsigned short ownPortNbr,
       unsigned int ownIpAddress, char *memmgrName, Dgr *dgr, DgrRC *rc)
           Establishes the application's access to DGR communication service.

           ownEngineId is the sending LTP engine ID that will characterize segments issued by
           this DGR service access point.  In order to prevent erroneous system behavior, never
           assign the same LTP engine ID to any two interoperating DGR SAPs.

           clientSvcId identifies the LTP client service to which all LTP segments issued by this
           DGR service access point will be directed.

           ownPortNbr is the port number to use for DGR service.  If zero, a system-assigned UDP
           port number is used.

           ownIpAddress is the Internet address of the network interface to use for DGR service.
           If zero, this argument defaults to the address of the interface identified by the
           local machine's host name.

           memmgrName is the name of the memory manager (see memmgr(3)) to use for dynamic memory
           management in DGR.  If NULL, defaults to the standard system malloc() and free()
           functions.

           dgr is the location in which to store the service access pointer that must be supplied
           on subsequent DGR function invocations.

           rc is the location in which to store the DGR return code resulting from the attempt to
           open this service access point (always DgrOpened).

           On any failure, returns -1.  On success, returns zero.

       void dgr_getsockname(Dgr dgr, unsigned short *portNbr, unsigned int *ipAddress)
           States the port number and IP address of the UDP socket used for this DGR service
           access point.

       void dgr_close(Dgr dgr)
           Reverses dgr_open(), releasing resources where possible.

       int dgr_send(Dgr dgr, unsigned short toPortNbr, unsigned int toIpAddress, int
       notificationFlags, char *content, int length, DgrRC *rc)
           Sends the indicated content, of length as indicated, to the remote DGR service access
           point identified by toPortNbr and toIpAddress.  The message will be retransmitted as
           necessary until either it is acknowledged or DGR determines that it cannot be
           delivered.

           notificationFlags, if non-zero, is the logical OR of the notification behaviors
           requested for this datagram.  Available behaviors are DGR_NOTE_FAILED (a notice of
           datagram delivery failure will issued if delivery of the datagram fails) and
           DGR_NOTE_ACKED (a notice of datagram delivery success will be issued if delivery of
           the datagram succeeds).  Notices are issued via dgr_receive() that is, the thread that
           calls dgr_receive() on this DGR service access point will receive these notices
           interspersed with inbound datagram contents.

           length of content must be greater than zero and may be as great as 65535, but lengths
           greater than 8192 may not be supported by the local underlying UDP implementation; to
           minimize the chance of data loss when transmitting over the internet, length should
           not exceed 512.

           rc is the location in which to store the DGR return code resulting from the attempt to
           send the content.

           On any failure, returns -1 and sets *rc to DgrFailed.  On success, returns zero.

       int dgr_receive(Dgr dgr, unsigned short *fromPortNbr, unsigned int *fromIpAddress, char
       *content, int *length, int *errnbr, int timeoutSeconds, DgrRC *rc)
           Delivers the oldest undelivered DGR event queued for delivery.

           DGR events are of two type: (a) messages received from a remote DGR service access
           point and (b) notices of previously sent messages that DGR has determined either have
           been or cannot be delivered, as requested in the notificationFlags parameters provided
           to the dgr_send() calls that sent those messages.

           In the former case, dgr_receive() will place the content of the inbound message in
           content, its length in length, and the IP address and port number of the sender in
           fromIpAddress and fromPortNbr, and it will set *rc to DgrDatagramReceived and return
           zero.

           In the latter case, dgr_receive() will place the content of the affected outbound
           message in content and its length in length and return zero.  If the event being
           reported is a delivery success, then DgrDatagramAcknowledged will be placed in *rc.
           Otherwise, DgrDatagramNotAcknowledged will be placed in *rc and the relevant errno (if
           any) will be placed in *errnbr.

           The content buffer should be at least 65535 bytes in length to enable delivery of the
           content of the received or delivered/undeliverable message.

           timeoutSeconds controls blocking behavior.  If timeoutSeconds is DGR_BLOCKING (i.e.,
           -1), dgr_receive() will not return until (a) there is either an inbound message to
           deliver or an outbound message delivery result to report, or (b) the function is
           interrupted by means of dgr_interrupt().  If timeoutSeconds is DGR_POLL (i.e., zero),
           dgr_receive() returns immediately; if there is currently no inbound message to deliver
           and no outbound message delivery result to report, the function sets *rc to
           DgrTimedOut and returns zero.  For any other positive value of timeoutSeconds,
           dgr_receive() returns after the indicated number of seconds have lapsed (in which case
           the returned value of *rc is DgrTimedOut), or when there is a message to deliver or a
           delivery result to report, or when the function is interrupted by means of
           dgr_interrupt(), whichever occurs first.  When the function returns due to
           interruption by dgr_interrupt(), the value placed in *rc is DgrInterrupted instead of
           DgrDatagramReceived.

           rc is the location in which to store the DGR return code resulting from the attempt to
           receive content.

           On any I/O error or other unrecoverable system error, returns -1.  Otherwise always
           returns zero, placing DgrFailed in *rc and writing a failure message in the event of
           an operating error.

       void dgr_interrupt(Dgr dgr)
           Interrupts a dgr_receive() invocation that is currently blocked.  Designed to be
           called from a signal handler; for this purpose, dgr may need to be obtained from a
           static variable.

SEE ALSO

       ltp(3), file2dgr(1), dgr2file(1)