NAME¶
ltp - Licklider Transmission Protocol (LTP) communications library
SYNOPSIS¶
#include "ltp.h"
typedef enum
{
LtpNoNotice = 0,
LtpExportSessionStart,
LtpXmitComplete,
LtpExportSessionCanceled,
LtpExportSessionComplete,
LtpRecvGreenSegment,
LtpRecvRedPart,
LtpImportSessionCanceled
} LtpNoticeType;
[see description for available functions]
DESCRIPTION¶
The ltp library provides functions enabling application software to use LTP to
send and receive information reliably over a long-latency link. It conforms to
the LTP specification as documented by the Delay-Tolerant Networking Research
Group of the Internet Research Task Force.
The LTP notion of
engine ID corresponds closely to the Internet notion of
a host, and in ION engine IDs are normally indistinguishable from node numbers
including the node numbers in Bundle Protocol endpoint IDs conforming to the
"ipn" scheme.
The LTP notion of
client ID corresponds closely to the Internet notion of
"protocol number" as used in the Internet Protocol. It enables data
from multiple applications -- clients -- to be multiplexed over a single
reliable link. However, for ION operations we normally use LTP exclusively for
the transmission of Bundle Protocol data, identified by client ID = 1.
- int ltp_attach()
- Attaches the application to LTP functionality on the lcoal computer.
Returns 0 on success, -1 on any error.
- void ltp_detach()
- Terminates all access to LTP functionality on the local computer.
- int ltp_engine_is_started()
- Returns 1 if the local LTP engine has been started and not yet stopped, 0
otherwise.
- 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 clientId as received at the remote
LTP engine identified by destinationEngineId.
clientServiceData must be a "zero-copy object" reference
as returned by zco_create(). Note that LTP 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.
redLength indicates the number of leading bytes of data in
clientServiceData 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
clientServiceData will be sent as "green" data, i.e.,
unreliably. If redLength is zero, the entire client service data
unit will be sent unreliably. If the entire client service data unit is to
be sent reliably, redLength may be simply be set to LTP_ALL_RED
(i.e., -1).
On success, the function populates *sessionId with the source engine
ID and the "session number" assigned to transmission of this
client service data unit and returns zero. The session number may be used
to link future LTP processing events, such as transmission cancellation,
to the affected client service data. ltp_send() returns -1 on any
error.
- int ltp_open(unsigned int clientId)
- Establishes the application's exclusive access to received service data
units tagged with the indicated client service data ID. At any time, only
a single application task is permitted to receive service data units for
any single client service data ID.
Returns 0 on success, -1 on any error (e.g., the indicated client service is
already being held open by some other application task).
- 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 LTP processing events pertaining to the flow of
service data units tagged with the indicated client service ID. The nature
of each event is indicated by *type. Additional parameters
characterizing the event are returned in *sessionId,
*reasonCode, *endOfBlock, *dataOffset,
*dataLength, and *data as relevant.
The value returned in *data is always a zero-copy object; use the
zco_* functions defined in "zco.h" to retrieve the content of
that object.
When the notice is an LtpRecvGreenSegment, the ZCO returned in *data
contains the content of a single LTP green segment. Reassembly of the
green part of some block from these segments is the responsibility of the
application.
When the notice is an LtpRecvRedPart, the ZCO returned in *data
contains the red part of a possibly aggregated block. The ZCO'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.
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 ZCO returned in
*data for each such notice is a service data unit ZCO that had
previously been passed to ltp_send().
ltp_get_notice() always blocks indefinitely until an LTP processing
event is delivered.
Returns zero on success, -1 on any error.
- void ltp_interrupt(unsigned int clientId)
- Interrupts an ltp_get_notice() invocation. This function is
designed to be called from a signal handler; for this purpose,
clientId may need to be obtained from a static variable.
- void ltp_release_data(Object data)
- Releases the resources allocated to hold data, a client service
data ZCO.
- void ltp_close(unsigned int clientId)
- Terminates the application's exclusive access to received service data
units tagged with the indicated client service data ID.
SEE ALSO¶
ltpadmin(1),
ltprc(5),
zco(3)