NAME¶
bssp - Bundle Streaming Service Protocol (BSSP) communications library
SYNOPSIS¶
#include "bssp.h"
typedef enum
{
BsspNoNotice = 0,
BsspXmitSuccess,
BsspXmitFailure,
BsspRecvSuccess
} BsspNoticeType;
[see description for available functions]
DESCRIPTION¶
The bssp library provides functions enabling application software to use BSSP to
send and receive streaming data in bundles.
BSSP 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, BSSP uses not
one but two underlying "link service" channels: (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,
and (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.
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 "protocol number" as used in the Internet Protocol. It enables
data from multiple applications -- clients -- to 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.
- int bssp_attach()
- Attaches the application to BSSP functionality on the lcoal computer.
Returns 0 on success, -1 on any error.
- void bssp_detach()
- Terminates all access to BSSP functionality on the local computer.
- int bssp_engine_is_started()
- Returns 1 if the local BSSP engine has been started and not yet stopped, 0
otherwise.
- 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.
inOrder is a Boolean value indicating whether or not the service
data item that is 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 that the item must
be transmitted using the "reliable" channel), 1 if yes (meaning
that 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.
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().
bssp_get_notice() always blocks indefinitely until an BSSP
processing event is delivered.
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.
- void bssp_release_data(Object data)
- Releases the resources allocated to hold data, a client service
data ZCO.
- 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.
SEE ALSO¶
bsspadmin(1),
bssprc(5),
zco(3)