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)