bp::doc::pod3::bp(3) BP library functions bp::doc::pod3::bp(3)
NAME
bp - Bundle Protocol communications library
SYNOPSIS
#include "bp.h"
[see description for available functions]
DESCRIPTION
The bp library provides functions enabling application software to use Bundle Protocol to send and receive information over a delay-
tolerant network. It conforms to the Bundle Protocol specification as documented in Internet RFC 5050.
int bp_attach( )
Attaches the application to BP functionality on the local computer. Returns 0 on success, -1 on any error.
Note that all ION libraries and applications draw memory dynamically, as needed, from a shared pool of ION working memory. The size of
the pool is established when ION node functionality is initialized by ionadmin(1). This is a precondition for initializing BP
functionality by running bpadmin(1), which in turn is required in order for bp_attach() to succeed.
Sdr bp_get_sdr( )
Returns handle for the SDR data store used for BP, to enable creation and interrogation of bundle payloads (application data units).
void bp_detach( )
Terminates access to BP functionality on the local computer. Detaching is required to avoid memory leaks.
int bp_open(char *eid, BpSAP *ionsapPtr)
Opens the application's access to the BP endpoint identified by eid, so that the application can take delivery of bundles destined for
the indicated endpoint and can send bundles whose source is the indicated endpoint. On success, places a value in *ionsapPtr that can
be supplied to future bp function invocations and returns 0. Returns -1 on any error.
int bp_send(BpSAP sap, int mode, char *destEid, char *reportToEid, int lifespan, int classOfService, BpCustodySwitch custodySwitch,
unsigned char srrFlags, int ackRequested, BpExtendedCOS *extendedCOS, Object adu, Object *newBundle)
Sends a bundle to the endpoint identified by destEid, from the source endpoint as provided to the bp_open() call that returned sap.
mode must be either BP_BLOCKING or BP_NONBLOCKING, as bp_send() does not support timeout intervals.
reportToEid identifies the endpoint to which any status reports pertaining to this bundle will be sent; if NULL, defaults to the source
endpoint.
lifespan is the maximum number of seconds that the bundle can remain in-transit (undelivered) in the network prior to automatic
deletion.
classOfService is simply priority for now: BP_BULK_PRIORITY, BP_STD_PRIORITY, or BP_EXPEDITED_PRIORITY. If class-of-service flags are
defined in a future version of Bundle Protocol, those flags would be OR'd with priority.
custodySwitch indicates whether or not custody transfer is requested for this bundle and, if so, whether or not the source node itself
is required to be the initial custodian. The valid values are SourceCustodyRequired, SourceCustodyOptional, NoCustodyRequired.
srrFlags, if non-zero, is the logical OR of the status reporting behaviors requested for this bundle: BP_RECEIVED_RPT, BP_CUSTODY_RPT,
BP_FORWARDED_RPT, BP_DELIVERED_RPT, BP_DELETED_RPT.
ackRequested is a Boolean parameter indicating whether or not the recipient application should be notified that the source application
requests some sort of application-specific end-to-end acknowledgment upon receipt of the bundle.
extendedCOS, if not NULL, is used to populate the Extended Class Of Service block for this bundle. The block's ordinal value is used
to provide fine-grained ordering within "expedited" traffic: ordinal values from 0 (the default) to 254 (used to designate the most
urgent traffic) are valid, with 255 reserved for custody signals. The value of the block's flags is the logical OR of the applicable
extended class-of-service flags:
BP_MINIMUM_LATENCY designates the bundle as "critical" for the purposes of Contact Graph Routing.
BP_BEST_EFFORT signifies that non-reliable convergence-layer protocols, as available, may be used to transmit the bundle. Notably,
the bundle may be sent as "green" data rather than "red" data when issued via LTP.
BP_FLOW_LABEL_PRESENT signifies whether or not the value of flowLabel in extendedCOS must be encoded into the ECOS block when the
bundle is transmitted.
adu must be a "zero-copy object" reference, as returned by zco_create(), containing the application data that is to be conveyed as the
bundle's payload.
The function returns 1 on success, 0 on transient failure, -1 on any other (i.e., system or application; permanent) error. If 1 is
returned, then the ADU has been accepted and queued for transmission in a bundle; in this case (and only in this case) the address of
the newly created bundle within the ION database is placed in newBundle, in case the bundle needs to be canceled in the future.
If 0 is returned, then either the destination endpoint was found to be NULL (in which case errno is zero) or else there is not
currently enough space for acceptance and queuing of this ADU (in which case errno has been set to EWOULDBLOCK). In the latter case,
which is possible only when mode is BP_NONBLOCKING, the application may abandon this transmission attempt or may wait briefly and then
try again.
int bp_track(Object bundle, Object trackingElt)
Adds trackingElt to the list of "tracking" references in bundle. trackingElt must be the address of an SDR list element -- whose data
is the address of this same bundle -- within some list of bundles that is privately managed by the application. Upon destruction of
the bundle this list element will automatically be deleted, thus removing the bundle from the application's privately managed list of
bundles. This enables the application to keep track of bundles that it is operating on without risk of inadvertently de-referencing
the address of a nonexistent bundle.
void bp_untrack(Object bundle, Object trackingElt)
Removes trackingElt from the list of "tracking" references in bundle, if it is in that list. Does not delete trackingElt itself.
int bp_suspend(Object bundle)
Suspends transmission of bundle. Has no effect if bundle is "critical" (i.e., has got extended class of service BP_MINIMUM_LATENCY
flag set) or if the bundle is already suspended. Otherwise, reverses the enqueuing of the bundle to its selected transmission outduct
and places it in the "limbo" queue until the suspension is lifted by calling bp_resume. Returns 0 on success, -1 on any error.
int bp_resume(Object bundle)
Terminates suspension of transmission of bundle. Has no effect if bundle is "critical" (i.e., has got extended class of service
BP_MINIMUM_LATENCY flag set) or is not suspended. Otherwise, removes the bundle from the "limbo" queue and queues it for route re-
computation and re-queuing. Returns 0 on success, -1 on any error.
int bp_cancel(Object bundle)
Cancels transmission of bundle. If the indicated bundle is currently queued for forwarding, transmission, or retransmission, it is
removed from the relevant queue and destroyed exactly as if its Time To Live had expired. Returns 0 on success, -1 on any error.
int bp_receive(BpSAP sap, BpDelivery *dlvBuffer, int timeoutSeconds)
Receives a bundle, or reports on some failure of bundle reception activity.
The "result" field of the dlvBuffer structure will be used to indicate the outcome of the data reception activity.
If at least one bundle destined for the endpoint for which this SAP is opened has not yet been delivered to the SAP, then the payload
of the oldest such bundle will be returned in dlvBuffer->adu and dlvBuffer->result will be set to BpPayloadPresent. If there is no
such bundle, bp_receive() blocks for up to timeoutSeconds while waiting for one to arrive.
If timeoutSeconds is BP_POLL (i.e., zero) and no bundle is awaiting delivery, or if timeoutSeconds is greater than zero but no bundle
arrives before timeoutSeconds have elapsed, then dlvBuffer->result will be set to BpReceptionTimedOut. If timeoutSeconds is
BP_BLOCKING (i.e., -1) then bp_receive() blocks until either a bundle arrives or the function is interrupted by an invocation of
bp_interrupt().
dlvBuffer->result will be set to BpReceptionInterrupted in the event that the calling process received and handled some signal other
than SIGALRM while waiting for a bundle.
The application data unit delivered in the data delivery structure, if any, will be a "zero-copy object" reference. Use zco reception
functions (see zco(3)) to read the content of the application data unit.
Be sure to call bp_release_delivery() after every successful invocation of bp_receive().
The function returns 0 on success, -1 on any error.
void bp_interrupt(BpSAP sap)
Interrupts a bp_receive() invocation that is currently blocked. This function is designed to be called from a signal handler; for this
purpose, sap may need to be obtained from a static variable.
void bp_release_delivery(BpDelivery *dlvBuffer, int releaseAdu)
Releases resources allocated to the indicated delivery. releaseAdu is a Boolean parameter: if non-zero, the ADU ZCO reference in
dlvBuffer (if any) is destroyed, causing the ZCO itself to be destroyed if no other references to it remain.
void bp_close(BpSAP sap)
Terminates the application's access to the BP endpoint identified by the eid cited by the indicated service access point. The
application relinquishes its ability to take delivery of bundles destined for the indicated endpoint and to send bundles whose source
is the indicated endpoint.
SEE ALSO
bpadmin(1), lgsend(1), lgagent(1), bpextensions(3), bprc(5), lgfile(5)
perl v5.14.2 2012-05-25 bp::doc::pod3::bp(3)