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.