.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "bp::doc::pod3::bp 3" .TH bp::doc::pod3::bp 3 "2012-05-25" "perl v5.14.2" "BP library functions" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" bp \- Bundle Protocol communications library .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include "bp.h" \& \& [see description for available functions] .Ve .SH "DESCRIPTION" .IX Header "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 \s-1RFC\s0 5050. .IP "int bp_attach( )" 4 .IX Item "int bp_attach( )" Attaches the application to \s-1BP\s0 functionality on the local computer. Returns 0 on success, \-1 on any error. .Sp Note that all \s-1ION\s0 libraries and applications draw memory dynamically, as needed, from a shared pool of \s-1ION\s0 working memory. The size of the pool is established when \s-1ION\s0 node functionality is initialized by \fIionadmin\fR\|(1). This is a precondition for initializing \s-1BP\s0 functionality by running \fIbpadmin\fR\|(1), which in turn is required in order for \fIbp_attach()\fR to succeed. .IP "Sdr bp_get_sdr( )" 4 .IX Item "Sdr bp_get_sdr( )" Returns handle for the \s-1SDR\s0 data store used for \s-1BP\s0, to enable creation and interrogation of bundle payloads (application data units). .IP "void bp_detach( )" 4 .IX Item "void bp_detach( )" Terminates access to \s-1BP\s0 functionality on the local computer. Detaching is required to avoid memory leaks. .IP "int bp_open(char *eid, BpSAP *ionsapPtr)" 4 .IX Item "int bp_open(char *eid, BpSAP *ionsapPtr)" Opens the application's access to the \s-1BP\s0 endpoint identified by \fIeid\fR, 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 \fI*ionsapPtr\fR that can be supplied to future bp function invocations and returns 0. Returns \-1 on any error. .IP "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)" 4 .IX Item "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 \fIdestEid\fR, from the source endpoint as provided to the \fIbp_open()\fR call that returned \fIsap\fR. .Sp \&\fImode\fR must be either \s-1BP_BLOCKING\s0 or \s-1BP_NONBLOCKING\s0, as \fIbp_send()\fR does not support timeout intervals. .Sp \&\fIreportToEid\fR identifies the endpoint to which any status reports pertaining to this bundle will be sent; if \s-1NULL\s0, defaults to the source endpoint. .Sp \&\fIlifespan\fR is the maximum number of seconds that the bundle can remain in-transit (undelivered) in the network prior to automatic deletion. .Sp \&\fIclassOfService\fR is simply priority for now: \s-1BP_BULK_PRIORITY\s0, \&\s-1BP_STD_PRIORITY\s0, or \s-1BP_EXPEDITED_PRIORITY\s0. If class-of-service flags are defined in a future version of Bundle Protocol, those flags would be \&\s-1OR\s0'd with priority. .Sp \&\fIcustodySwitch\fR 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. .Sp \&\fIsrrFlags\fR, if non-zero, is the logical \s-1OR\s0 of the status reporting behaviors requested for this bundle: \s-1BP_RECEIVED_RPT\s0, \s-1BP_CUSTODY_RPT\s0, \s-1BP_FORWARDED_RPT\s0, \&\s-1BP_DELIVERED_RPT\s0, \s-1BP_DELETED_RPT\s0. .Sp \&\fIackRequested\fR 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. .Sp \&\fIextendedCOS\fR, if not \s-1NULL\s0, is used to populate the Extended Class Of Service block for this bundle. The block's \fIordinal\fR value is used to provide fine-grained ordering within \*(L"expedited\*(R" 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 \&\fIflags\fR is the logical \s-1OR\s0 of the applicable extended class-of-service flags: .RS 4 .Sp .RS 4 \&\s-1BP_MINIMUM_LATENCY\s0 designates the bundle as \*(L"critical\*(R" for the purposes of Contact Graph Routing. .Sp \&\s-1BP_BEST_EFFORT\s0 signifies that non-reliable convergence-layer protocols, as available, may be used to transmit the bundle. Notably, the bundle may be sent as \*(L"green\*(R" data rather than \*(L"red\*(R" data when issued via \s-1LTP\s0. .Sp \&\s-1BP_FLOW_LABEL_PRESENT\s0 signifies whether or not the value of \fIflowLabel\fR in \fIextendedCOS\fR must be encoded into the \s-1ECOS\s0 block when the bundle is transmitted. .RE .RE .RS 4 .Sp \&\fIadu\fR must be a \*(L"zero-copy object\*(R" reference, as returned by \fIzco_create()\fR, containing the application data that is to be conveyed as the bundle's payload. .Sp 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 \&\s-1ADU\s0 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 \&\s-1ION\s0 database is placed in \fInewBundle\fR, in case the bundle needs to be canceled in the future. .Sp If 0 is returned, then either the destination endpoint was found to be \&\s-1NULL\s0 (in which case errno is zero) or else there is not currently enough space for acceptance and queuing of this \s-1ADU\s0 (in which case errno has been set to \s-1EWOULDBLOCK\s0). In the latter case, which is possible only when \fImode\fR is \s-1BP_NONBLOCKING\s0, the application may abandon this transmission attempt or may wait briefly and then try again. .RE .IP "int bp_track(Object bundle, Object trackingElt)" 4 .IX Item "int bp_track(Object bundle, Object trackingElt)" Adds \fItrackingElt\fR to the list of \*(L"tracking\*(R" references in \fIbundle\fR. \&\fItrackingElt\fR must be the address of an \s-1SDR\s0 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. .IP "void bp_untrack(Object bundle, Object trackingElt)" 4 .IX Item "void bp_untrack(Object bundle, Object trackingElt)" Removes \fItrackingElt\fR from the list of \*(L"tracking\*(R" references in \fIbundle\fR, if it is in that list. Does not delete \fItrackingElt\fR itself. .IP "int bp_suspend(Object bundle)" 4 .IX Item "int bp_suspend(Object bundle)" Suspends transmission of \fIbundle\fR. Has no effect if bundle is \*(L"critical\*(R" (i.e., has got extended class of service \s-1BP_MINIMUM_LATENCY\s0 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 \&\*(L"limbo\*(R" queue until the suspension is lifted by calling bp_resume. Returns 0 on success, \-1 on any error. .IP "int bp_resume(Object bundle)" 4 .IX Item "int bp_resume(Object bundle)" Terminates suspension of transmission of \fIbundle\fR. Has no effect if bundle is \*(L"critical\*(R" (i.e., has got extended class of service \&\s-1BP_MINIMUM_LATENCY\s0 flag set) or is not suspended. Otherwise, removes the bundle from the \*(L"limbo\*(R" queue and queues it for route re-computation and re-queuing. Returns 0 on success, \-1 on any error. .IP "int bp_cancel(Object bundle)" 4 .IX Item "int bp_cancel(Object bundle)" Cancels transmission of \fIbundle\fR. 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. .IP "int bp_receive(BpSAP sap, BpDelivery *dlvBuffer, int timeoutSeconds)" 4 .IX Item "int bp_receive(BpSAP sap, BpDelivery *dlvBuffer, int timeoutSeconds)" Receives a bundle, or reports on some failure of bundle reception activity. .Sp The \*(L"result\*(R" field of the dlvBuffer structure will be used to indicate the outcome of the data reception activity. .Sp If at least one bundle destined for the endpoint for which this \s-1SAP\s0 is opened has not yet been delivered to the \s-1SAP\s0, then the payload of the oldest such bundle will be returned in \fIdlvBuffer\fR\->\fIadu\fR and \&\fIdlvBuffer\fR\->\fIresult\fR will be set to BpPayloadPresent. If there is no such bundle, \fIbp_receive()\fR blocks for up to \fItimeoutSeconds\fR while waiting for one to arrive. .Sp If \fItimeoutSeconds\fR is \s-1BP_POLL\s0 (i.e., zero) and no bundle is awaiting delivery, or if \fItimeoutSeconds\fR is greater than zero but no bundle arrives before \fItimeoutSeconds\fR have elapsed, then \fIdlvBuffer\fR\->\fIresult\fR will be set to BpReceptionTimedOut. If \fItimeoutSeconds\fR is \s-1BP_BLOCKING\s0 (i.e., \-1) then \fIbp_receive()\fR blocks until either a bundle arrives or the function is interrupted by an invocation of \fIbp_interrupt()\fR. .Sp \&\fIdlvBuffer\fR\->\fIresult\fR will be set to BpReceptionInterrupted in the event that the calling process received and handled some signal other than \s-1SIGALRM\s0 while waiting for a bundle. .Sp The application data unit delivered in the data delivery structure, if any, will be a \*(L"zero-copy object\*(R" reference. Use zco reception functions (see \fIzco\fR\|(3)) to read the content of the application data unit. .Sp Be sure to call \fIbp_release_delivery()\fR after every successful invocation of \&\fIbp_receive()\fR. .Sp The function returns 0 on success, \-1 on any error. .IP "void bp_interrupt(BpSAP sap)" 4 .IX Item "void bp_interrupt(BpSAP sap)" Interrupts a \fIbp_receive()\fR invocation that is currently blocked. This function is designed to be called from a signal handler; for this purpose, \&\fIsap\fR may need to be obtained from a static variable. .IP "void bp_release_delivery(BpDelivery *dlvBuffer, int releaseAdu)" 4 .IX Item "void bp_release_delivery(BpDelivery *dlvBuffer, int releaseAdu)" Releases resources allocated to the indicated delivery. \fIreleaseAdu\fR is a Boolean parameter: if non-zero, the \s-1ADU\s0 \s-1ZCO\s0 reference in \fIdlvBuffer\fR (if any) is destroyed, causing the \s-1ZCO\s0 itself to be destroyed if no other references to it remain. .IP "void bp_close(BpSAP sap)" 4 .IX Item "void bp_close(BpSAP sap)" Terminates the application's access to the \s-1BP\s0 endpoint identified by the \fIeid\fR 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. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIbpadmin\fR\|(1), \fIlgsend\fR\|(1), \fIlgagent\fR\|(1), \fIbpextensions\fR\|(3), \fIbprc\fR\|(5), \fIlgfile\fR\|(5)