bssp::doc::pod3::bssp(3)

💖 bssp — the Bundle Streaming Service Protocol (BSSP) communications library 💖

okay bestie, buckle up, because this is the bssp::doc::pod3::bssp(3) page from the BSSP library functions manual and it's literally the whole vibe of streaming bundles over space internet 🛰️✨

---

✨ NAME ✨

bssp — the Bundle Streaming Service Protocol (BSSP) communications library. that's it, that's the name, she's an icon 💅

---

🌸 SYNOPSIS 🌸

#include "bssp.h"

typedef enum
{
    BsspNoNotice = 0,
    BsspXmitSuccess,
    BsspXmitFailure,
    BsspRecvSuccess
} BsspNoticeType;

[see description for available functions]

so you pull in bssp.h, you get this cute lil enum of notice types (BsspNoNotice is 0, then BsspXmitSuccess, BsspXmitFailure, BsspRecvSuccess in that order, no cap), and then the actual functions are all down in the description, iykyk 🦋

---

👑 DESCRIPTION 👑

The bssp library hands you the functions that let application software use BSSP to send and receive streaming data in bundles. fr fr, that's the whole job.

BSSP is designed to forward streaming data in original transmission order wherever possible, but to retransmit data as necessary to make sure the entire stream is available for playback eventually. To pull that off, BSSP doesn't use one underlying "link service" channel — it uses two:

• (a) an unreliable "best efforts" channel, for data items that are successfully received upon initial transmission over every extent of the end-to-end path 🌈
• (b) a "reliable" channel, for data items that were lost at some point, had to be retransmitted, and therefore are now out of order 💀

The BSS library at the destination node supports immediate "real-time" display of all data received on the "best efforts" channel in transmission order, together with database retention of all data eventually received on the "reliable" channel. two moods, one library, periodt.

The BSSP 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 BSSP notion of client ID corresponds closely to the Internet notion of a "protocol number" as used in the Internet Protocol. It lets data from multiple applications — clients — be multiplexed over a single reliable link. However, for ION operations we normally use BSSP exclusively for the transmission of Bundle Protocol data, identified by client ID = 1. remember that number, bestie, it's the main character 🔥

---

🎀 the functions, one by one 🎀

• int bssp_attach() — attaches the application to BSSP functionality on the local computer. returns 0 on success, -1 on any error. she's your entry point, be nice to her 🫶
• void bssp_detach() — terminates all access to BSSP functionality on the local computer. the goodbye hug 🤗
• int bssp_engine_is_started() — returns 1 if the local BSSP engine has been started and not yet stopped, 0 otherwise. a vibe check, basically ✨
• 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 clientId as received at the remote BSSP engine identified by destinationEngineId.

clientServiceData must be a "zero-copy object" reference as returned by zco_create(). Note that BSSP 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. so like, no awkward custody drama, she handles her own 💅

inOrder is a Boolean value indicating whether or not the service data item being sent is "in order", i.e. was originally transmitted after all items that have previously been sent to this destination by this local BSSP engine:

• 0 if no (meaning the item must be transmitted using the "reliable" channel)
• 1 if yes (meaning the item must be transmitted using the "best-efforts" channel)

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 BSSP processing events to the affected client service data. bssp_send() returns -1 on any error.

• int bssp_open(unsigned int clientId) — establishes the application's exclusive access to received service data units tagged with the indicated BSSP 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. it's giving "this seat is taken" 😤

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 bssp_get_notice(unsigned int clientId, BsspNoticeType *type, BsspSessionId *sessionId, unsigned char *reasonCode, unsigned int *dataLength, Object *data) — receives notices of BSSP 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, *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 BsspRecvSuccess, the ZCO returned in *data contains the content of a single BSSP block.

The cancellation of an export session results in delivery of a BsspXmitFailure notice. In this case, the ZCO returned in *data is a service data unit ZCO that had previously been passed to bssp_send().

heads up: bssp_get_notice() always blocks indefinitely until an BSSP processing event is delivered. no timeout, no escape hatch, she waits 😭

Returns zero on success, -1 on any error.

• void bssp_interrupt(unsigned int clientId) — interrupts an bssp_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. (yes bestie, static, that's the trick 🧚)
• void bssp_release_data(Object data) — releases the resources allocated to hold data, a client service data ZCO. clean up after yourself, queen 🎀
• void bssp_close(unsigned int clientId) — terminates the application's exclusive access to received service data units tagged with the indicated client service data ID. the door is open again, slay 🚪✨

---

🌈 SEE ALSO 🌈

bsspadmin(1), bssprc(5), zco(3)

go read those too, they're all in the same friend group 💜

---

and that's the whole page, bestie!! this absolute banger was rendered by perl v5.24.1 and stamped 2016-07-07 — yeah she's vintage, and she's still serving. take care of your ZCOs, respect the exclusive access, and may your best-efforts channel never let you down 🦋💖✨