NAME

       dtpc - Delay-Tolerant Payload Conditioning (DTPC) communications library

SYNOPSIS

           #include "dtpc.h"

           [see description for available functions]

DESCRIPTION

       The dtpc library provides functions enabling application software to use Delay-Tolerant
       Payload Conditioning (DTPC) when exchanging information over a delay-tolerant network.
       DTPC is an application service protocol, running in a layer immediately above Bundle
       Protocol, that offers delay-tolerant support for several end-to-end services to
       applications that may require them.  These services include delivery of application data
       items in transmission (rather than reception) order; detection of reception gaps in the
       sequence of transmitted application data items, with end-to-end negative acknowledgment of
       the missing data; end-to-end positive acknowledgment of successfully received data; end-
       to-end retransmission of missing data, driven either by negative acknowledgment or timer
       expiration; suppression of duplicate application data items; aggregation of small
       application data items into large bundle payloads, to reduce bundle protocol overhead; and
       application-controlled elision of redundant data items in aggregated payloads, to improve
       link utiliization.

       int dptc_attach( )
           Attaches the application to DTPC functionality on the local computer.  Returns 0 on
           success, -1 on any error.

       void dptc_detach( )
           Terminates all access to DTPC functionality on the local computer.

       int dtpc_entity_is_started( )
           Returns 1 if the local DTPC entity has been started and not yet stopped, 0 otherwise.

       int dtpc_open(unsigned int topicID, DtpcElisionFn elisionFn, DtpcSAP *dtpcsapPtr)
           Establishes the application as the sole authorized client for posting and receiving
           application data items on topic topicID within the local BP node.  On success, the
           service access point for posting and receiving such data items is placed in
           *dtpcsapPtr, the elision callback function elisionFn (if not NULL) is associated with
           this topic, and 0 is returned.  Returns -1 on any error.

       int dtpc_send(unsigned int profileID, DtpcSAP sap, char *destEid, unsigned int maxRtx,
       unsigned int aggrSizeLimit, unsigned int aggrTimeLimit, int lifespan, BpExtendedCOS
       *extendedCOS, unsigned char srrFlags, BpCustodySwitch custodySwitch, char *reportToEid,
       int classOfService, Object item, unsigned int length)
           Inserts an application data item into an outbound DTPC application data unit destined
           for destEid.

           Transmission of that outbound ADU will be subject to the profile identified by
           profileID, as asserted by dtpcadmin(1), if profileID is non-zero.  In that case,
           maxRtx, aggrSizeLimit, aggrTimeLimit, lifespan, extendedCOS, srrFlags, custodySwitch,
           reportToEid, and classOfService are ignored.

           If profileID is zero then the profile asserted by dtpcadmin(1) that matches maxRtx,
           aggrSizeLimit, aggrTimeLimit, lifespan, extendedCOS, srrFlags, custodySwitch,
           reportToEid, and classOfService will govern transmission of the ADU, unless no such
           profile has been asserted, in which case dtpc_send() returns 0 indicating user error.

           maxRtx is the maximum number of times any single DTPC ADU transmitted subject to the
           indicated profile may be retransmitted by the DTPC entity.  If maxRtx is zero, then
           the DTPC transport service features (in-order delivery, end-to-end acknowledgment,
           etc.) are disabled for this profile.

           aggrSizeLimit is the size threshold for concluding aggregation of an outbound ADU and
           requesting transmission of that ADU.  If aggrSizeLimit is zero, then the DTPC
           transmission optimization features (aggregation and elision) are disabled for this
           profile.

           aggrTimeLimit is the time threshold for concluding aggregation of an outbound ADU and
           requesting transmission of that ADU.  If aggrTimeLimit is zero, then the DTPC
           transmission optimization features (aggregation and elision) are disabled for this
           profile.

           lifespan, extendedCOS, srrFlags, custodySwitch, reportToEid, and classOfService are as
           defined for bp_send (see bp(3)).

           item must be an object allocated within ION's SDR "heap", and length must be the
           length of that object.  The item will be inserted into the outbound ADU's list of data
           items posted for the topic associated with sap, and the elision callback function
           declared for sap (if any, and if the applicable profile does not disable transmission
           optimization features) will be invoked immediately after insertion of the application
           data item but before DTPC makes any decision on whether or not to initiate
           transmission of the outbound ADU.

           The function returns 1 on success, 0 on any user application error, -1 on any system
           error.

       int dtpc_receive(DtpcSAP sap, DtpcDelivery *dlvBuffer, int timeoutSeconds)
           Receives a single DTPC application data item, or reports on some failure of DTPC
           reception activity.

           The "result" field of the dlvBuffer structure will be used to indicate the outcome of
           the data reception activity.

           If at least one application data item on the topic associated with sap has not yet
           been delivered to the SAP, then the payload of the oldest such item will be returned
           in dlvBuffer->adu and dlvBuffer->result will be set to PayloadPresent.  If there is no
           such item, dtpc_receive() blocks for up to timeoutSeconds while waiting for one to
           arrive.

           If timeoutSeconds is DTPC_POLL (i.e., zero) and no application data item is awaiting
           delivery, or if timeoutSeconds is greater than zero but no item arrives before
           timeoutSeconds have elapsed, then dlvBuffer->result will be set to ReceptionTimedOut.
           If timeoutSeconds is DTPC_BLOCKING (i.e., -1) then bp_receive() blocks until either an
           item arrives or the function is interrupted by an invocation of dtpc_interrupt().

           dlvBuffer->result will be set to ReceptionInterrupted in the event that the calling
           process received and handled some signal other than SIGALRM while waiting for a
           bundle.

           dlvBuffer->result will be set to DtpcServiceStopped in the event that DTPC service has
           been terminated on the local node.

           The application data item delivered in the DTPC delivery structure, if any, will be an
           object allocated within ION's SDR "heap"; the length of that object will likewise be
           provided in the DtpcDelivery structure.

           Be sure to call dtpc_release_delivery() after every successful invocation of
           dtpc_receive().

           The function returns 0 on success, -1 on any error.

       void dtpc_interrupt(DtpcSAP sap)
           Interrupts a dtpc_receive() invocation that is currently blocked.  This function is
           designed to be called from a signal handler; for this purpose, sap may need to be
           obtained from a static variable.

       void dtpc_release_delivery(DtpcDelivery *dlvBuffer)
           Releases resources allocated to the indicated DTPC delivery.

       void dtpc_close(DtpcSAP sap)
           Removes the application as the sole authorized client for posting and receiving
           application data items on the topic indicated in sap within the local BP node.  The
           application relinquishes its ability to send and receive application data items on the
           indicated topic.

SEE ALSO

       dtpcadmin(1), dtpcrc(5), bp(3)