table of contents
other versions
other sections
bp::doc::pod3::bp(3) | BP library functions | bp::doc::pod3::bp(3) |
NAME¶
bp - Bundle Protocol communications librarySYNOPSIS¶
#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.
- 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.
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.
- 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.
- 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)2012-05-25 | perl v5.14.2 |