--- name: "dtpc" section: "3" platform: "linux" package: "ion-doc" version: "3.2.1+dfsg-1.1" release: "Debian 9 (Stretch)" platforms: ["linux"] url: "https://new.carta.tech/dtpc" --- # dtpc(3) Delay-Tolerant Payload Conditioning (DTPC) communications library ## 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)](/dtpcadmin/1.md), 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)](/dtpcadmin/1.md) 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)](/bp/3.md)). *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)](/dtpcadmin/1.md), [*dtpcrc*(5)](/dtpcrc/5.md), [*bp*(3)](/bp/3.md)