bss::doc::pod3::bss(3)

📦 version 3.2.1, in ubuntu jammy

💖 NAME 💖

bss — the Bundle Streaming Service library, bestie. that's it, that's the name 🫶

it's the manual page for bss, living in section 3 of the BSS library functions docs. okay so let's get into it ✨

✨ SYNOPSIS ✨

#include "bss.h"

typedef int (*RTBHandler)(time_t time, unsigned long count, char *buffer, int bufLength);

[see description for available functions]
the functions themselves are all down in the description, okay?? don't come for me, that's literally what the original says 💅

🌸 DESCRIPTION 🌸

okay so the BSS library is the whole vibe behind streaming data over delay-tolerant networking (DTN) bundles. 🦋

the intent of the library is iconic honestly: it lets applications take streaming data that arrives in transmission time order (read: no time regressions, no going backwards, periodt) and hand it off to an application-specific "display" function — notionally for immediate real-time display. but — and this is the key part — it also stores all the received data, including the out-of-order stuff, in a private database so you can play it back under user control later. 🎀

the reception and real-time display of in-order data? that's handled by a background thread. so the application's main (foreground) thread is left free to respond to user commands controlling playback or whatever other application-specific functions you got going on. main character energy for the foreground thread fr fr 👑

🧚 the display function (RTBHandler)

the application-specific "display" function that the background thread calls has to conform to the RTBHandler type definition. rules:

  • it must return 0 on success
  • it must return -1 on any error that should terminate the background thread

and here's the thing: only on return from this function will the background thread proceed to acquire the next BSS payload. so like. don't be slow in there bestie 😭

🍓 the database files

all data acquired by the BSS background thread gets written to a BSS database. that database is made of three files: table, list, and data. 💖

the name of the database is the root name common to all three files. so for example:

db3.tbl, db3.lst, db3.dat

would be the three files making up the db3 BSS database. cute right?? 🥰

important: all three files of the selected BSS database must reside in the same directory of the file system. no splitting them up across directories, that's not the move 🙈

🌈 the navigation state structure

several of the replay navigation functions in the BSS library need the application to provide a navigation state structure of type bssNav, as defined in the bss.h header file.

and like — the application is not responsible for populating this structure. it's strictly for the private use of the BSS library. hands off, it's not yours 💅

💅 the functions, one by one

int bssOpen(char *bssName, char *path, char *eid)

opens access to a BSS database, so you can do 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 (yes literally, just ignore it, it's giving decorative 🌸)

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 — 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
  • bufLen — the length of that buffer
heads up bestie: received bundle payloads in excess of this length will be discarded. gone. poof. 💀

handler identifies the display function to which each in-order bundle payload will be passed. the parameters passed to this function work like this:

  • time and count — identify the received bundle, indicating the bundle's creation timestamp time (in seconds) and counter value
  • buffer and bufLength — 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, and 0 otherwise. a return value of -1 from handler will terminate the BSS data acquisition background thread. 😭 periodt.

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(). two for one, we love efficiency 🫶

on any failure, returns -1. on success, returns zero.

void bssClose()

terminates data playback access to the most recently opened BSS database. bye bye 👋

void bssStop()

terminates the most recently initiated BSS data acquisition background thread. 🛑

void bssExit()

a convenience function that performs both bssClose() and bssStop(). the "i'm done here" combo meal 🍓

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: bssRead() cannot be successfully called until nav has been populated — nominally by a preceding call to bssSeek(), bssNext(), or bssPrev(). no nav, no read. that's the rule 💅

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. seek then read, one call, obsessed 🥰

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) — go read that one too bestie, iykyk 💜

and that's the whole page!! 🌈

this little love letter to the BSS library functions was documented by perl v5.24.1, dated 2016-07-07 — yeah she's been around a minute but she still ate and left no crumbs 💅✨ mwah, go stream some bundles responsibly 🎀🦋

📦 where this page comes from