.\" 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 "bss::doc::pod3::bss 3"
.TH bss::doc::pod3::bss 3 "2016-07-07" "perl v5.24.1" "BSS 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"
bss \- Bundle Streaming Service library
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    #include "bss.h"
\&
\&    typedef int (*RTBHandler)(time_t time, unsigned long count, char *buffer, int bufLength);
\&
\&    [see description for available functions]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \s-1BSS\s0 library supports the streaming of data over delay-tolerant
networking (\s-1DTN\s0) bundles.  The intent of the library is to enable applications
that pass streaming data received in transmission time order (i.e., without
time regressions) to an application-specific \*(L"display\*(R" function \*(-- notionally
for immediate real-time display \*(-- but to store \fBall\fR received data (including
out-of-order data) in a private database for playback under user control.  The
reception and real-time display of in-order data is performed by a background
thread, leaving the application's main (foreground) thread free to respond to
user commands controlling playback or other application-specific functions.
.PP
The application-specific \*(L"display\*(R" function invoked by the background thread
must conform to the RTBHandler type definition.  It must return 0 on success,
\&\-1 on any error that should terminate the background thread.  Only on return
from this function will the background thread proceed to acquire the next \s-1BSS\s0
payload.
.PP
All data acquired by the \s-1BSS\s0 background thread is written to a \s-1BSS\s0 database
comprising three files: table, list, and data.  The name of the database
is the root name that is common to the three files, e.g., \fIdb3\fR.tbl,
\&\fIdb3\fR.lst, \fIdb3\fR.dat would be the three files making up the \fIdb3\fR \s-1BSS\s0
database.  All three files of the selected \s-1BSS\s0 database must reside in the
same directory of the file system.
.PP
Several replay navigation functions in the \s-1BSS\s0 library require that the
application provide a navigation state structure of type bssNav as defined
in the bss.h header file.  The application is not reponsible for populating
this structure; it's strictly for the private use of the \s-1BSS\s0 library.
.IP "int bssOpen(char *bssName, char *path, char *eid)" 4
.IX Item "int bssOpen(char *bssName, char *path, char *eid)"
Opens access to a \s-1BSS\s0 database, to enable data playback.  \fIbssName\fR
identifies the specific \s-1BSS\s0 database that is to be opened.  \fIpath\fR identifies
the directory in which the database resides.  \fIeid\fR is ignored.  On any
failure, returns \-1.  On success, returns zero.
.IP "int bssStart(char *bssName, char *path, char *eid, char *buffer, int bufLen, RTBHandler handler)" 4
.IX Item "int bssStart(char *bssName, char *path, char *eid, char *buffer, int bufLen, RTBHandler handler)"
Starts a \s-1BSS\s0 data acquisition background thread.  \fIbssName\fR identifies the
\&\s-1BSS\s0 database into which data will be acquired.  \fIpath\fR identifies the
directory in which that database resides.  \fIeid\fR is used to open the \s-1BP\s0
endpoint at which the delivered \s-1BSS\s0 bundle payload contents will be
acquired.  \fIbuffer\fR identifies a data acquisition buffer, which must be
provided by the application, and \fIbufLen\fR indicates the length of that
buffer; received bundle payloads in excess of this length will be discarded.
.Sp
\&\fIhandler\fR identifies the display function to which each in-order bundle
payload will be passed.  The \fItime\fR and \fIcount\fR parameters passed to this
function identify the received bundle, indicating the bundle's creation
timestamp time (in seconds) and counter value.  The \fIbuffer\fR and \fIbufLength\fR
parameters indicate the location into which the bundle's payload was
acquired and the length of the acquired payload.  \fIhandler\fR must return \-1 on
any unrecoverable system error, 0 otherwise.  A return value of \-1 from
\&\fIhandler\fR will terminate the \s-1BSS\s0 data acquisition background thread.
.Sp
On any failure, returns \-1.  On success, returns zero.
.IP "int bssRun(char *bssName, char *path, char *eid, char *buffer, int bufLen, RTBHandler handler)" 4
.IX Item "int bssRun(char *bssName, char *path, char *eid, char *buffer, int bufLen, RTBHandler handler)"
A convenience function that performs both \fIbssOpen()\fR and \fIbssStart()\fR.  On any
failure, returns \-1.  On success, returns zero.
.IP "void \fIbssClose()\fR" 4
.IX Item "void bssClose()"
Terminates data playback access to the most recently opened \s-1BSS\s0 database.
.IP "void \fIbssStop()\fR" 4
.IX Item "void bssStop()"
Terminates the most recently initiated \s-1BSS\s0 data acquisition background thread.
.IP "void \fIbssExit()\fR" 4
.IX Item "void bssExit()"
A convenience function that performs both \fIbssClose()\fR and \fIbssStop()\fR.
.IP "long bssRead(bssNav nav, char *data, int dataLen)" 4
.IX Item "long bssRead(bssNav nav, char *data, int dataLen)"
Copies the data at the current playback position in the database, as indicated
by \fInav\fR, into \fIdata\fR; if the length of the data is in excess of \fIdataLen\fR
then an error condition is asserted (i.e., \-1 is returned).  Note that \fIbssRead()\fR
cannot be successfully called until \fInav\fR has been populated, nominally by
a preceding call to \fIbssSeek()\fR, \fIbssNext()\fR, or \fIbssPrev()\fR.  Returns the length
of data read, or \-1 on any error.
.IP "long bssSeek(bssNav *nav, time_t time, time_t *curTime, unsigned long *count)" 4
.IX Item "long bssSeek(bssNav *nav, time_t time, time_t *curTime, unsigned long *count)"
Sets the current playback position in the database, in \fInav\fR, to the data
received in the bundle with the earliest creation time that was greater than
or equal to \fItime\fR.  Populates \fInav\fR and also returns the creation time and
bundle \s-1ID\s0 count of that bundle in \fIcurTime\fR and \fIcount\fR.  Returns the length
of data at this location, or \-1 on any error.
.IP "long bssSeek_read(bssNav *nav, time_t time, time_t *curTime, unsigned long *count, char *data, int dataLen)" 4
.IX Item "long bssSeek_read(bssNav *nav, time_t time, time_t *curTime, unsigned long *count, char *data, int dataLen)"
A convenience function that performs \fIbssSeek()\fR followed by an immediate
\&\fIbssRead()\fR to return the data at the new playback position.  Returns the length
of data read, or \-1 on any error.
.IP "long bssNext(bssNav *nav, time_t *curTime, unsigned long *count)" 4
.IX Item "long bssNext(bssNav *nav, time_t *curTime, unsigned long *count)"
Sets the playback position in the database, in \fInav\fR, to the data received
in the bundle with the earliest creation time and \s-1ID\s0 count greater than that
of the bundle at the current playback position.  Populates \fInav\fR and also
returns the creation time and bundle \s-1ID\s0 count of that bundle in \fIcurTime\fR
and \fIcount\fR.  Returns the length of data at this location (if any),
\&\-2 on reaching end of list, or \-1 on any error.
.IP "long bssNext_read(bssNav *nav, time_t *curTime, unsigned long *count, char *data, int dataLen)" 4
.IX Item "long bssNext_read(bssNav *nav, time_t *curTime, unsigned long *count, char *data, int dataLen)"
A convenience function that performs \fIbssNext()\fR followed by an immediate
\&\fIbssRead()\fR to return the data at the new playback position.  Returns the
length of data read, \-2 on reaching end of list, or \-1 on any error.
.IP "long bssPrev(bssNav *nav, time_t *curTime, unsigned long *count)" 4
.IX Item "long bssPrev(bssNav *nav, time_t *curTime, unsigned long *count)"
Sets the playback position in the database, in \fInav\fR, to the data received
in the bundle with the latest creation time and \s-1ID\s0 count earlier than that
of the bundle at the current playback position.  Populates \fInav\fR and also
returns the creation time and bundle \s-1ID\s0 count of that bundle in \fIcurTime\fR
and \fIcount\fR.  Returns the length of data at this location (if any), \-2 on
reaching end of list, or \-1 on any error.
.IP "long bssPrev_read(bssNav *nav, time_t *curTime, unsigned long *count, char *data, int dataLen)" 4
.IX Item "long bssPrev_read(bssNav *nav, time_t *curTime, unsigned long *count, char *data, int dataLen)"
A convenience function that performs \fIbssPrev()\fR followed by an immediate
\&\fIbssRead()\fR to return the data at the new playback position.  Returns the
length of data read, \-2 on reaching end of list, or \-1 on any error.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbp\fR\|(3)