NAME¶
bss - Bundle Streaming Service library
SYNOPSIS¶
#include "bss.h"
typedef int (*RTBHandler)(time_t time, unsigned long count, char *buffer, int bufLength);
[see description for available functions]
DESCRIPTION¶
The BSS library supports the streaming of data over delay-tolerant networking
(DTN) 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 "display" function --
notionally for immediate real-time display -- but to store
all 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.
The application-specific "display" 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 BSS payload.
All data acquired by the BSS background thread is written to a BSS 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.,
db3.tbl,
db3.lst,
db3.dat would be the three files making up the
db3 BSS database. All three files of the selected BSS database must
reside in the same directory of the file system.
Several replay navigation functions in the BSS 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 BSS library.
- int bssOpen(char *bssName, char *path, char *eid)
- Opens access to a BSS database, to enable data playback. bssName
identifies the specific BSS database that is to be opened. path
identifies the directory in which the database resides. eid is
ignored. On any failure, returns -1. On success, returns zero.
- int bssStart(char *bssName, char *path, char *eid, char *buffer, int
bufLen, RTBHandler handler)
- Starts a BSS data acquisition background thread. bssName identifies
the BSS database into which data will be acquired. path identifies
the directory in which that database resides. eid is used to open
the BP endpoint at which the delivered BSS bundle payload contents will be
acquired. buffer identifies a data acquisition buffer, which must
be provided by the application, and bufLen indicates the length of
that buffer; received bundle payloads in excess of this length will be
discarded.
handler identifies the display function to which each in-order
bundle payload will be passed. The time and count parameters
passed to this function identify the received bundle, indicating the
bundle's creation timestamp time (in seconds) and counter value. The
buffer and bufLength parameters indicate the location into
which the bundle's payload was acquired and the length of the acquired
payload. handler must return -1 on any unrecoverable system error,
0 otherwise. A return value of -1 from handler will terminate the
BSS data acquisition background thread.
On any failure, returns -1. On success, returns zero.
- int bssRun(char *bssName, char *path, char *eid, char *buffer, int bufLen,
RTBHandler handler)
- A convenience function that performs both bssOpen() and
bssStart(). On any failure, returns -1. On success, returns
zero.
- void bssClose()
- Terminates data playback access to the most recently opened BSS
database.
- void bssStop()
- Terminates the most recently initiated BSS data acquisition background
thread.
- void bssExit()
- A convenience function that performs both bssClose() and
bssStop().
- long bssRead(bssNav nav, char *data, int dataLen)
- Copies the data at the current playback position in the database, as
indicated by nav, into data; if the length of the data is in
excess of dataLen then an error condition is asserted (i.e., -1 is
returned). Note that bssRead() cannot be successfully called until
nav has been populated, nominally by a preceding call to
bssSeek(), bssNext(), or bssPrev(). Returns the
length of data read, or -1 on any error.
- long bssSeek(bssNav *nav, time_t time, time_t *curTime, unsigned long
*count)
- Sets the current playback position in the database, in nav, to the
data received in the bundle with the earliest creation time that was
greater than or equal to time. Populates nav and also
returns the creation time and bundle ID count of that bundle in
curTime and count. Returns the length of data at this
location, or -1 on any error.
- long bssSeek_read(bssNav *nav, time_t time, time_t *curTime, unsigned long
*count, char *data, int dataLen)
- A convenience function that performs bssSeek() followed by an
immediate bssRead() to return the data at the new playback
position. Returns the length of data read, or -1 on any error.
- long bssNext(bssNav *nav, time_t *curTime, unsigned long *count)
- Sets the playback position in the database, in nav, to the data
received in the bundle with the earliest creation time and ID count
greater than that of the bundle at the current playback position.
Populates nav and also returns the creation time and bundle ID
count of that bundle in curTime and count. Returns the
length of data at this location (if any), -2 on reaching end of list, or
-1 on any error.
- long bssNext_read(bssNav *nav, time_t *curTime, unsigned long *count, char
*data, int dataLen)
- A convenience function that performs bssNext() followed by an
immediate bssRead() 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.
- long bssPrev(bssNav *nav, time_t *curTime, unsigned long *count)
- Sets the playback position in the database, in nav, to the data
received in the bundle with the latest creation time and ID count earlier
than that of the bundle at the current playback position. Populates
nav and also returns the creation time and bundle ID count of that
bundle in curTime and count. Returns the length of data at
this location (if any), -2 on reaching end of list, or -1 on any
error.
- long bssPrev_read(bssNav *nav, time_t *curTime, unsigned long *count, char
*data, int dataLen)
- A convenience function that performs bssPrev() followed by an
immediate bssRead() 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.
SEE ALSO¶
bp(3)