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)