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.