.\" 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 "bssp::doc::pod3::bssp 3"
.TH bssp::doc::pod3::bssp 3 "2016-07-07" "perl v5.24.1" "BSSP 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"
bssp \- Bundle Streaming Service Protocol (BSSP) communications library
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    #include "bssp.h"
\&
\&    typedef enum
\&    {
\&        BsspNoNotice = 0,
\&        BsspXmitSuccess,
\&        BsspXmitFailure,
\&        BsspRecvSuccess
\&    } BsspNoticeType;
\&
\&    [see description for available functions]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The bssp library provides functions enabling application software to use \s-1BSSP\s0
to send and receive streaming data in bundles.
.PP
\&\s-1BSSP\s0 is designed to forward streaming data in original transmission order
wherever possible but to retransmit data as necessary to ensure that the
entire stream is available for playback eventually.  To this end, \s-1BSSP\s0 uses
not one but two underlying \*(L"link service\*(R" channels: (a) an unreliable \*(L"best
efforts\*(R" channel, for data items that are successfully received upon initial
transmission over every extent of the end-to-end path, and (b) a \*(L"reliable\*(R"
channel, for data items that were lost at some point, had to be retransmitted,
and therefore are now out of order.  The \s-1BSS\s0 library at the destination node
supports immediate \*(L"real-time\*(R" display of all data received on the \*(L"best
efforts\*(R" channel in transmission order, together with database retention of
all data eventually received on the \*(L"reliable\*(R" channel.
.PP
The \s-1BSSP\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-1BSSP\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-1BSSP\s0 exclusively for the
transmission of Bundle Protocol data, identified by client \s-1ID\s0 = 1.
.IP "int \fIbssp_attach()\fR" 4
.IX Item "int bssp_attach()"
Attaches the application to \s-1BSSP\s0 functionality on the lcoal computer.  Returns
0 on success, \-1 on any error.
.IP "void \fIbssp_detach()\fR" 4
.IX Item "void bssp_detach()"
Terminates all access to \s-1BSSP\s0 functionality on the local computer.
.IP "int \fIbssp_engine_is_started()\fR" 4
.IX Item "int bssp_engine_is_started()"
Returns 1 if the local \s-1BSSP\s0 engine has been started and not yet stopped,
0 otherwise.
.IP "int bssp_send(uvast destinationEngineId, unsigned int clientId, Object clientServiceData, int inOrder, BsspSessionId *sessionId)" 4
.IX Item "int bssp_send(uvast destinationEngineId, unsigned int clientId, Object clientServiceData, int inOrder, BsspSessionId *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-1BSSP\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-1BSSP\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
\&\fIinOrder\fR is a Boolean value indicating whether or not the service data item
that is being sent is \*(L"in order\*(R", i.e., was originally transmitted after all
items that have previously been sent to this destination by this local \s-1BSSP\s0
engine: 0 if no (meaning that the item must be transmitted using the
\&\*(L"reliable\*(R" channel), 1 if yes (meaning that the item must be transmitted
using the \*(L"best-efforts\*(R" channel.
.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-1BSSP\s0 processing events to the affected client service data.  \fIbssp_send()\fR
returns \-1 on any error.
.IP "int bssp_open(unsigned int clientId)" 4
.IX Item "int bssp_open(unsigned int clientId)"
Establishes the application's exclusive access to received service data
units tagged with the indicated \s-1BSSP\s0 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 bssp_get_notice(unsigned int clientId, BsspNoticeType *type, BsspSessionId *sessionId, unsigned char *reasonCode, unsigned int *dataLength, Object *data)" 4
.IX Item "int bssp_get_notice(unsigned int clientId, BsspNoticeType *type, BsspSessionId *sessionId, unsigned char *reasonCode, unsigned int *dataLength, Object *data)"
Receives notices of \s-1BSSP\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*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 BsspRecvSuccess, the \s-1ZCO\s0 returned in \fI*data\fR
contains the content of a single \s-1BSSP\s0 block.
.Sp
The cancellation of an export session results in delivery of a 
BsspXmitFailure notice.  In this case, the \s-1ZCO\s0 returned in *data is a
service data unit \s-1ZCO\s0 that had previously been passed to \fIbssp_send()\fR.
.Sp
\&\fIbssp_get_notice()\fR always blocks indefinitely until an \s-1BSSP\s0 processing event
is delivered.
.Sp
Returns zero on success, \-1 on any error.
.IP "void bssp_interrupt(unsigned int clientId)" 4
.IX Item "void bssp_interrupt(unsigned int clientId)"
Interrupts an \fIbssp_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 bssp_release_data(Object data)" 4
.IX Item "void bssp_release_data(Object data)"
Releases the resources allocated to hold \fIdata\fR, a client service data \s-1ZCO.\s0
.IP "void bssp_close(unsigned int clientId)" 4
.IX Item "void bssp_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"
\&\fIbsspadmin\fR\|(1), \fIbssprc\fR\|(5), \fIzco\fR\|(3)