.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "dtpc::doc::pod3::dtpc 3" .TH dtpc::doc::pod3::dtpc 3 "2016-07-07" "perl v5.24.1" "DTPC library functions" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" dtpc \- Delay\-Tolerant Payload Conditioning (DTPC) communications library .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include "dtpc.h" \& \& [see description for available functions] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The dtpc library provides functions enabling application software to use Delay-Tolerant Payload Conditioning (\s-1DTPC\s0) when exchanging information over a delay-tolerant network. \s-1DTPC\s0 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. .IP "int dptc_attach( )" 4 .IX Item "int dptc_attach( )" Attaches the application to \s-1DTPC\s0 functionality on the local computer. Returns 0 on success, \-1 on any error. .IP "void dptc_detach( )" 4 .IX Item "void dptc_detach( )" Terminates all access to \s-1DTPC\s0 functionality on the local computer. .IP "int dtpc_entity_is_started( )" 4 .IX Item "int dtpc_entity_is_started( )" Returns 1 if the local \s-1DTPC\s0 entity has been started and not yet stopped, 0 otherwise. .IP "int dtpc_open(unsigned int topicID, DtpcElisionFn elisionFn, DtpcSAP *dtpcsapPtr)" 4 .IX Item "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 \fItopicID\fR within the local \s-1BP\s0 node. On success, the service access point for posting and receiving such data items is placed in \fI*dtpcsapPtr\fR, the elision callback function \&\fIelisionFn\fR (if not \s-1NULL\s0) is associated with this topic, and 0 is returned. Returns \-1 on any error. .IP "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)" 4 .IX Item "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 \s-1DTPC\s0 application data unit destined for \fIdestEid\fR. .Sp Transmission of that outbound \s-1ADU\s0 will be subject to the profile identified by \fIprofileID\fR, as asserted by \fIdtpcadmin\fR\|(1), if \fIprofileID\fR is non-zero. In that case, \fImaxRtx\fR, \fIaggrSizeLimit\fR, \fIaggrTimeLimit\fR, \fIlifespan\fR, \&\fIextendedCOS\fR, \fIsrrFlags\fR, \fIcustodySwitch\fR, \fIreportToEid\fR, and \&\fIclassOfService\fR are ignored. .Sp If \fIprofileID\fR is zero then the profile asserted by \fIdtpcadmin\fR\|(1) that matches \&\fImaxRtx\fR, \fIaggrSizeLimit\fR, \fIaggrTimeLimit\fR, \fIlifespan\fR, \fIextendedCOS\fR, \&\fIsrrFlags\fR, \fIcustodySwitch\fR, \fIreportToEid\fR, and \fIclassOfService\fR will govern transmission of the \s-1ADU,\s0 unless no such profile has been asserted, in which case \fIdtpc_send()\fR returns 0 indicating user error. .Sp \&\fImaxRtx\fR is the maximum number of times any single \s-1DTPC ADU\s0 transmitted subject to the indicated profile may be retransmitted by the \s-1DTPC\s0 entity. If \&\fImaxRtx\fR is zero, then the \s-1DTPC\s0 transport service features (in-order delivery, end-to-end acknowledgment, etc.) are disabled for this profile. .Sp \&\fIaggrSizeLimit\fR is the size threshold for concluding aggregation of an outbound \s-1ADU\s0 and requesting transmission of that \s-1ADU. \s0 If \fIaggrSizeLimit\fR is zero, then the \s-1DTPC\s0 transmission optimization features (aggregation and elision) are disabled for this profile. .Sp \&\fIaggrTimeLimit\fR is the time threshold for concluding aggregation of an outbound \s-1ADU\s0 and requesting transmission of that \s-1ADU. \s0 If \fIaggrTimeLimit\fR is zero, then the \s-1DTPC\s0 transmission optimization features (aggregation and elision) are disabled for this profile. .Sp \&\fIlifespan\fR, \fIextendedCOS\fR, \fIsrrFlags\fR, \fIcustodySwitch\fR, \fIreportToEid\fR, and \fIclassOfService\fR are as defined for bp_send (see \fIbp\fR\|(3)). .Sp \&\fIitem\fR must be an object allocated within \s-1ION\s0's \s-1SDR \s0\*(L"heap\*(R", and \fIlength\fR must be the length of that object. The item will be inserted into the outbound \&\s-1ADU\s0's list of data items posted for the topic associated with \fIsap\fR, and the elision callback function declared for \fIsap\fR (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 \s-1DTPC\s0 makes any decision on whether or not to initiate transmission of the outbound \s-1ADU.\s0 .Sp The function returns 1 on success, 0 on any user application error, \-1 on any system error. .IP "int dtpc_receive(DtpcSAP sap, DtpcDelivery *dlvBuffer, int timeoutSeconds)" 4 .IX Item "int dtpc_receive(DtpcSAP sap, DtpcDelivery *dlvBuffer, int timeoutSeconds)" Receives a single \s-1DTPC\s0 application data item, or reports on some failure of \&\s-1DTPC\s0 reception activity. .Sp The \*(L"result\*(R" field of the dlvBuffer structure will be used to indicate the outcome of the data reception activity. .Sp If at least one application data item on the topic associated with \fIsap\fR has not yet been delivered to the \s-1SAP,\s0 then the payload of the oldest such item will be returned in \fIdlvBuffer\fR\->\fIadu\fR and \fIdlvBuffer\fR\->\fIresult\fR will be set to PayloadPresent. If there is no such item, \fIdtpc_receive()\fR blocks for up to \fItimeoutSeconds\fR while waiting for one to arrive. .Sp If \fItimeoutSeconds\fR is \s-1DTPC_POLL \s0(i.e., zero) and no application data item is awaiting delivery, or if \fItimeoutSeconds\fR is greater than zero but no item arrives before \fItimeoutSeconds\fR have elapsed, then \fIdlvBuffer\fR\->\fIresult\fR will be set to ReceptionTimedOut. If \fItimeoutSeconds\fR is \s-1DTPC_BLOCKING \&\s0(i.e., \-1) then \fIbp_receive()\fR blocks until either an item arrives or the function is interrupted by an invocation of \fIdtpc_interrupt()\fR. .Sp \&\fIdlvBuffer\fR\->\fIresult\fR will be set to ReceptionInterrupted in the event that the calling process received and handled some signal other than \s-1SIGALRM\s0 while waiting for a bundle. .Sp \&\fIdlvBuffer\fR\->\fIresult\fR will be set to DtpcServiceStopped in the event that \s-1DTPC\s0 service has been terminated on the local node. .Sp The application data item delivered in the \s-1DTPC\s0 delivery structure, if any, will be an object allocated within \s-1ION\s0's \s-1SDR \s0\*(L"heap\*(R"; the length of that object will likewise be provided in the DtpcDelivery structure. .Sp Be sure to call \fIdtpc_release_delivery()\fR after every successful invocation of \&\fIdtpc_receive()\fR. .Sp The function returns 0 on success, \-1 on any error. .IP "void dtpc_interrupt(DtpcSAP sap)" 4 .IX Item "void dtpc_interrupt(DtpcSAP sap)" Interrupts a \fIdtpc_receive()\fR invocation that is currently blocked. This function is designed to be called from a signal handler; for this purpose, \&\fIsap\fR may need to be obtained from a static variable. .IP "void dtpc_release_delivery(DtpcDelivery *dlvBuffer)" 4 .IX Item "void dtpc_release_delivery(DtpcDelivery *dlvBuffer)" Releases resources allocated to the indicated \s-1DTPC\s0 delivery. .IP "void dtpc_close(DtpcSAP sap)" 4 .IX Item "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 \fIsap\fR within the local \s-1BP\s0 node. The application relinquishes its ability to send and receive application data items on the indicated topic. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIdtpcadmin\fR\|(1), \fIdtpcrc\fR\|(5), \fIbp\fR\|(3)