.\" 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 "ltp::doc::pod3::ltp 3"
.TH ltp::doc::pod3::ltp 3 "2016-07-07" "perl v5.24.1" "LTP 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"
ltp \- Licklider Transmission Protocol (LTP) communications library
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    #include "ltp.h"
\&
\&    typedef enum
\&    {
\&        LtpNoNotice = 0,
\&        LtpExportSessionStart,
\&        LtpXmitComplete,
\&        LtpExportSessionCanceled,
\&        LtpExportSessionComplete,
\&        LtpRecvGreenSegment,
\&        LtpRecvRedPart,
\&        LtpImportSessionCanceled
\&    } LtpNoticeType;
\&
\&    [see description for available functions]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The ltp library provides functions enabling application software to use \s-1LTP\s0
to send and receive information reliably over a long-latency link.  It
conforms to the \s-1LTP\s0 specification as documented by the Delay-Tolerant
Networking Research Group of the Internet Research Task Force.
.PP
The \s-1LTP\s0 notion of \fBengine \s-1ID\s0\fR corresponds closely to the Internet notion of
a host, and in \s-1ION\s0 engine IDs are normally indistinguishable from node numbers
including the node numbers in Bundle Protocol endpoint IDs conforming to
the \*(L"ipn\*(R" scheme.
.PP
The \s-1LTP\s0 notion of \fBclient \s-1ID\s0\fR corresponds closely to the Internet notion of
\&\*(L"protocol number\*(R" as used in the Internet Protocol.  It enables data from
multiple applications \*(-- clients \*(-- to be multiplexed over a single reliable
link.  However, for \s-1ION\s0 operations we normally use \s-1LTP\s0 exclusively for the
transmission of Bundle Protocol data, identified by client \s-1ID\s0 = 1.
.IP "int \fIltp_attach()\fR" 4
.IX Item "int ltp_attach()"
Attaches the application to \s-1LTP\s0 functionality on the lcoal computer.  Returns
0 on success, \-1 on any error.
.IP "void \fIltp_detach()\fR" 4
.IX Item "void ltp_detach()"
Terminates all access to \s-1LTP\s0 functionality on the local computer.
.IP "int \fIltp_engine_is_started()\fR" 4
.IX Item "int ltp_engine_is_started()"
Returns 1 if the local \s-1LTP\s0 engine has been started and not yet stopped,
0 otherwise.
.IP "int ltp_send(uvast destinationEngineId, unsigned int clientId, Object clientServiceData, unsigned int redLength, LtpSessionId *sessionId)" 4
.IX Item "int ltp_send(uvast destinationEngineId, unsigned int clientId, Object clientServiceData, unsigned int redLength, LtpSessionId *sessionId)"
Sends a client service data unit to the application that is waiting for
data tagged with the indicated \fIclientId\fR as received at the remote \s-1LTP\s0
engine identified by \fIdestinationEngineId\fR.
.Sp
\&\fIclientServiceData\fR must be a \*(L"zero-copy object\*(R" reference as returned
by \fIzco_create()\fR.  Note that \s-1LTP\s0 will privately make and destroy its own
reference to the client service data object; the application is free to
destroy its reference at any time.
.Sp
\&\fIredLength\fR indicates the number of leading bytes of data in
\&\fIclientServiceData\fR that are to be sent reliably, i.e., with selective
retransmission in response to explicit or implicit negative acknowledgment
as necessary.  All remaining bytes of data in \fIclientServiceData\fR will be
sent as \*(L"green\*(R" data, i.e., unreliably.  If \fIredLength\fR is zero, the entire
client service data unit will be sent unreliably.  If the entire client
service data unit is to be sent reliably, \fIredLength\fR may be simply be set
to \s-1LTP_ALL_RED \s0(i.e., \-1).
.Sp
On success, the function populates \fI*sessionId\fR with the source engine \s-1ID\s0
and the \*(L"session number\*(R" assigned to transmission of this client service
data unit and returns zero.  The session number may be used to link future
\&\s-1LTP\s0 processing events, such as transmission cancellation, to the affected
client service data.  \fIltp_send()\fR returns \-1 on any error.
.IP "int ltp_open(unsigned int clientId)" 4
.IX Item "int ltp_open(unsigned int clientId)"
Establishes the application's exclusive access to received service data
units tagged with the indicated client service data \s-1ID. \s0 At any time, only
a single application task is permitted to receive service data units for
any single client service data \s-1ID.\s0
.Sp
Returns 0 on success, \-1 on any error (e.g., the indicated client service
is already being held open by some other application task).
.IP "int ltp_get_notice(unsigned int clientId, LtpNoticeType *type, LtpSessionId *sessionId, unsigned char *reasonCode, unsigned char *endOfBlock, unsigned int *dataOffset, unsigned int *dataLength, Object *data)" 4
.IX Item "int ltp_get_notice(unsigned int clientId, LtpNoticeType *type, LtpSessionId *sessionId, unsigned char *reasonCode, unsigned char *endOfBlock, unsigned int *dataOffset, unsigned int *dataLength, Object *data)"
Receives notices of \s-1LTP\s0 processing events pertaining to the flow of service
data units tagged with the indicated client service \s-1ID. \s0 The nature of each
event is indicated by \fI*type\fR.  Additional parameters characterizing the
event are returned in \fI*sessionId\fR, \fI*reasonCode\fR, \fI*endOfBlock\fR,
\&\fI*dataOffset\fR, \fI*dataLength\fR, and \fI*data\fR as relevant.
.Sp
The value returned in \fI*data\fR is always a zero-copy object; use the
zco_* functions defined in \*(L"zco.h\*(R" to retrieve the content of that object.
.Sp
When the notice is an LtpRecvGreenSegment, the \s-1ZCO\s0 returned in \fI*data\fR
contains the content of a single \s-1LTP\s0 green segment.  Reassembly of the
green part of some block from these segments is the responsibility of
the application.
.Sp
When the notice is an LtpRecvRedPart, the \s-1ZCO\s0 returned in \fI*data\fR
contains the red part of a possibly aggregated block.  The \s-1ZCO\s0's content
may therefore comprise multiple service data objects.  Extraction of
individual service data objects from the aggregated block is the
responsibility of the application.  A simple way to do this is to
prepend the length of the service data object to the object itself
(using zco_prepend_header) before calling ltp_send, so that the
receiving application can alternate extraction of object lengths and
objects from the delivered block's red part.
.Sp
The cancellation of an export session may result in delivery of multiple
LtpExportSessionCanceled notices, one for each service data unit in the
export session's (potentially) aggregated block.  The \s-1ZCO\s0 returned in
\&\fI*data\fR for each such notice is a service data unit \s-1ZCO\s0 that had previously
been passed to \fIltp_send()\fR.
.Sp
\&\fIltp_get_notice()\fR always blocks indefinitely until an \s-1LTP\s0 processing event
is delivered.
.Sp
Returns zero on success, \-1 on any error.
.IP "void ltp_interrupt(unsigned int clientId)" 4
.IX Item "void ltp_interrupt(unsigned int clientId)"
Interrupts an \fIltp_get_notice()\fR invocation.  This function is designed to be
called from a signal handler; for this purpose, \fIclientId\fR may need to be
obtained from a static variable.
.IP "void ltp_release_data(Object data)" 4
.IX Item "void ltp_release_data(Object data)"
Releases the resources allocated to hold \fIdata\fR, a client service data \s-1ZCO.\s0
.IP "void ltp_close(unsigned int clientId)" 4
.IX Item "void ltp_close(unsigned int clientId)"
Terminates the application's exclusive access to received service data
units tagged with the indicated client service data \s-1ID.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIltpadmin\fR\|(1), \fIltprc\fR\|(5), \fIzco\fR\|(3)