.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" 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::bpextensions 3"
.TH bp::doc::pod3::bpextensions 3 "2016-07-07" "perl v5.24.1" "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"
bpextensions \- interface for adding extensions to Bundle Protocol
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    #include "bpextensions.c"
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1ION\s0's interface for extending the Bundle Protocol enables the definition
of external functions that insert \fIextension\fR blocks into outbound bundles
(either before or after the payload block), parse and record extension
blocks in inbound bundles, and modify extension blocks at key points in
bundle processing.  All extension-block handling is statically linked into
\&\s-1ION\s0 at build time, but the addition of an extension never requires that
any standard \s-1ION\s0 source code be modified.
.PP
Standard structures for recording extension blocks \*(-- both in transient
storage [memory] during bundle acquisition (AcqExtBlock) and in persistent
storage [the \s-1ION\s0 database] during subsequent bundle processing (ExtensionBlock)
\&\*(-- are defined in the \fIbpP.h\fR header file.  In each case, the extension
block structure comprises a block \fItype\fR code, block processing \fIflags\fR,
possibly a list of \fI\s-1EID\s0 references\fR, an array of \fIbytes\fR (the
serialized form of the block, for transmission), the \fIlength\fR of that
array, optionally an extension-specific opaque \fIobject\fR whose structure
is designed to characterize the block in a manner that's convenient for
the extension processing functions, and the \fIsize\fR of that object.
.PP
The definition of each extension is asserted in an ExtensionDef structure,
also as defined in the \fIbpP.h\fR header file.  Each ExtensionDef must supply:
.Sp
.RS 4
The name of the extension.  (Used in some diagnostic messages.)
.Sp
The extension's block type code.
.Sp
An indication as to whether the local node is to insert this extension block
before (0) or after (1) the payload block when new bundles are locally sourced.
.Sp
A pointer to an \fBoffer\fR function.
.Sp
A pointer to a \fBrelease\fR function.
.Sp
A pointer to an \fBaccept\fR function.
.Sp
A pointer to a \fBcheck\fR function.
.Sp
A pointer to a \fBrecord\fR function.
.Sp
A pointer to a \fBclear\fR function.
.Sp
A pointer to a \fBcopy\fR function.
.Sp
A pointer to a function to be called when \fBforwarding\fR a bundle containing
this sort of block.
.Sp
A pointer to a function to be called when \fBtaking custody\fR of a bundle
containing this sort of block.
.Sp
A pointer to a function to be called when \fBenqueuing\fR for transmission a
bundle containing this sort of block.
.Sp
A pointer to a function to be called when a convergence-layer adapter
\&\fBdequeues\fR a bundle containing this sort of block, before serializing it.
.Sp
A pointer to a function to be called immediately before a convergence-layer
adapter \fBtransmits\fR a bundle containing this sort of block, after the
bundle has been serialized.
.RE
.PP
All extension definitions must be coded into an array of ExtensionDef
structures named \fIextensions\fR.  The order of appearance of extension
definitions in the extensions array determines the order in which
extension blocks will be inserted into locally sourced bundles.
.PP
The standard extensions array \*(-- which is empty \*(-- is in the
\&\fInoextensions.c\fR prototype source file.  The procedure for extending
the Bundle Protocol in \s-1ION\s0 is as follows:
.PP
1.  Specify \-DBP_EXTENDED in the Makefile's compiler command line when
building the libbpP.c library module.
.PP
2.  Create a copy of the prototype extensions file, named \*(L"bpextensions.c\*(R",
in a directory that is made visible to the Makefile's libbpP.c compilation
command line (by a \-I parameter).
.PP
3.  In the \*(L"external function declarations\*(R" area of \*(L"bpextensions.c\*(R", add
\&\*(L"extern\*(R" function declarations identifying the functions that will implement
your extension (or extensions).
.PP
4.  Add one or more ExtensionDef structure initialization lines to the
extensions array, referencing those declared functions.
.PP
5.  Develop the implementations of those functions in one or more new source
code files.
.PP
6.  Add the object file or files for the new extension implementation source
file (or files) to the Makefile's command line for linking libbpP.so.
.PP
The function pointers supplied in each ExtensionDef must conform to the
following specifications.  \s-1NOTE\s0 that any function that modifies the \fIbytes\fR
member of an ExtensionBlock or AckExtBlock \fBmust\fR set the corresponding
\&\fIlength\fR to the new length of the \fIbytes\fR array, if changed.
.IP "int (*BpExtBlkOfferFn)(ExtensionBlock *blk, Bundle *bundle)" 4
.IX Item "int (*BpExtBlkOfferFn)(ExtensionBlock *blk, Bundle *bundle)"
Populates all fields of the indicated ExtensionBlock structure
for inclusion in the indicated outbound bundle.  This function is
automatically called when a new bundle is locally sourced or
upon acquisition of a remotely sourced bundle that does not
contain an extension block of this type.  The values of the extension
block are typically expected to be a function of the state of the bundle,
but this is extension-specific.  If it is not appropriate to offer an
extension block of this type as part of this bundle, then the \fIsize\fR,
\&\fIlength\fR, \fIobject\fR, and \fIbytes\fR members of \fIblk\fR must all be set to
zero.  If it is appropriate to offer such a block but no internal object
representing the state of the block is needed, the \fIobject\fR and \fIsize\fR
members of \fIblk\fR must be set to zero.  The \fItype\fR, \fIblkProcFlags\fR, and
\&\fIdataLength\fR members of \fIblk\fR must be populated by the implementation of
the \*(L"offer\*(R" function, but the \fIlength\fR and \fIbytes\fR members are typically
populated by calling the \s-1BP\s0 library function \fIserializeExtBlk()\fR, which must
be passed the block to be serialized (with \fItype\fR, \fIblkProcFlags\fR and
\&\fIdataLength\fR already set), a Lyst of \s-1EID\s0 references (two list elements
\&\*(-- offsets \*(-- per \s-1EID\s0 reference, if applicable; otherwise \s-1NULL\s0), and a
pointer to the extension-specific block data.  The block's \fIbytes\fR array
and \fIobject\fR (if present) must occupy space allocated from the \s-1ION\s0 database
heap.  Return zero on success, \-1 on any system failure.
.IP "void (*BpExtBlkReleaseFn)(ExtensionBlock *blk)" 4
.IX Item "void (*BpExtBlkReleaseFn)(ExtensionBlock *blk)"
Releases all \s-1ION\s0 database space occupied by the \fIobject\fR member of \fIblk\fR.
This function is automatically called when a bundle is destroyed.  Note that
incorrect implementation of this function may result in a database space leak.
.IP "int (*BpExtBlkRecordFn)(ExtensionBlock *blk, AcqExtBlock *acqblk)" 4
.IX Item "int (*BpExtBlkRecordFn)(ExtensionBlock *blk, AcqExtBlock *acqblk)"
Copies the \fIobject\fR member of \fIacqblk\fR to \s-1ION\s0 database heap space and
places the address of that non-volatile object in the \fIobject\fR member of
\&\fIblk\fR; also sets \fIsize\fR in \fIblk\fR.  This function is automatically called
when an acquired bundle is accepted for forwarding and/or delivery.  Return
zero on success, \-1 on any system failure.
.IP "int (*BpExtBlkCopyFn)(ExtensionBlock *newblk, ExtensionBlock *oldblk)" 4
.IX Item "int (*BpExtBlkCopyFn)(ExtensionBlock *newblk, ExtensionBlock *oldblk)"
Copies the \fIobject\fR member of \fIoldblk\fR to \s-1ION\s0 database heap space and
places the address of that new non-volatile object in the \fIobject\fR member of
\&\fInewblk\fR, also sets \fIsize\fR in \fInewblk\fR.  This function is automatically
called when two copies of a bundle are needed, e.g., in the event that it
must both be delivered to a local client and also fowarded to another node.
Return zero on success, \-1 on any system failure.
.IP "int (*BpExtBlkProcessFn)(ExtensionBlock *blk, Bundle *bundle, void *context)" 4
.IX Item "int (*BpExtBlkProcessFn)(ExtensionBlock *blk, Bundle *bundle, void *context)"
Performs some extension-specific transformation of the data encapsulated in
\&\fIblk\fR based on the state of \fIbundle\fR.  The transformation to be performed
will typically vary depending on whether the identified function is the one
that is automatically invoked upon forwarding the bundle, upon taking custody
of the bundle, upon enqueuing the bundle for transmission, upon removing
the bundle from the transmission queue, or upon transmitting the serialized
bundle.  The \fIcontext\fR argument may supply useful supplemental information;
in particular, the context provided to the \s-1ON_DEQUEUE\s0 function will comprise
the name of the protocol for the duct from which the bundle has been dequeued,
together with the \s-1EID\s0 of the neighboring node endpoint to which the bundle
will be directly transmitted when serialized.  The block-specific data in \fIblk\fR
is located within \fIbytes\fR immediately after the header of the extension
block; the length of the block's header is the difference between \fIlength\fR
and \fIdataLength\fR.  Whenever the block's \fIblkProcFlags\fR, \s-1EID\s0 extensions,
and/or block-specific data are altered, the \fIserializeExtBlk()\fR function should
be called again to recalculate the size of the extension block and rebuild
the \fIbytes\fR array.  Return zero on success, \-1 on any system failure.
.IP "int (*BpAcqExtBlkAcquireFn)(AcqExtBlock *acqblk, AcqWorkArea *work)" 4
.IX Item "int (*BpAcqExtBlkAcquireFn)(AcqExtBlock *acqblk, AcqWorkArea *work)"
Populates the indicated AcqExtBlock structure with \fIsize\fR and \fIobject\fR
for retention as part of the indicated inbound bundle.  (The \fItype\fR,
\&\fIblkProcFlags\fR, \s-1EID\s0 references (if any), \fIdataLength\fR, \fIlength\fR, and
\&\fIbytes\fR values of the structure are pre-populated with data as extracted
from the serialized bundle.)  This function is automatically called
when an extension block of this type is encountered in the course of
parsing and acquiring a bundle for local delivery and/or forwarding.  If
no internal object representing the state of the block is needed, the
\&\fIobject\fR member of \fIacqblk\fR must be set to \s-1NULL\s0 and the \fIsize\fR
member must be set to zero.  If an \fIobject\fR is needed for this block,
it must occupy space that is allocated from \s-1ION\s0 working memory using
\&\fB\s-1MTAKE\s0\fR and its \fIsize\fR must be indicated in \fIblk\fR.  Return zero if
the block is malformed (this will cause the bundle to be discarded), 1 if
the block is successfully parsed, \-1 on any system failure.
.IP "int (*BpAcqExtBlkCheckFn)(AcqExtBlock *acqblk, AcqWorkArea *work)" 4
.IX Item "int (*BpAcqExtBlkCheckFn)(AcqExtBlock *acqblk, AcqWorkArea *work)"
Examines the bundle in \fIwork\fR to determine whether or not it is authentic,
in the context of the indicated extension block.  Return 1 if the block is
determined to be inauthentic (this will cause the bundle to be discarded),
zero if no inauthenticity is detected, \-1 on any system failure.
.IP "void (*BpAcqExtBlkClearFn)(AcqExtBlock *acqblk)" 4
.IX Item "void (*BpAcqExtBlkClearFn)(AcqExtBlock *acqblk)"
Uses \fB\s-1MRELEASE\s0\fR to release all \s-1ION\s0 working memory occupied by the \fIobject\fR
member of \fIacqblk\fR.  This function is automatically called when acquisition
of a bundle is completed, whether or not the bundle is accepted.  Note that
incorrect implementation of this function may result in a working memory leak.
.SS "\s-1UTILITY FUNCTIONS FOR EXTENSION PROCESSING\s0"
.IX Subsection "UTILITY FUNCTIONS FOR EXTENSION PROCESSING"
.IP "void discardExtensionBlock(AcqExtBlock *blk)" 4
.IX Item "void discardExtensionBlock(AcqExtBlock *blk)"
Deletes this block from the bundle acquisition work area prior to the
recording of the bundle in the \s-1ION\s0 database.
.IP "void scratchExtensionBlock(ExtensionBlock *blk)" 4
.IX Item "void scratchExtensionBlock(ExtensionBlock *blk)"
Deletes this block from the bundle after the bundle has been recorded in the
\&\s-1ION\s0 database.
.IP "Object findExtensionBlock(Bundle *bundle, unsigned int type, unsigned int listIdx)" 4
.IX Item "Object findExtensionBlock(Bundle *bundle, unsigned int type, unsigned int listIdx)"
On success, returns the address of the ExtensionBlock in \fIbundle\fR for the
indicated \fItype\fR and \fIlistIdx\fR.  If no such extension block exists, returns
zero.
.IP "int serializeExtBlk(ExtensionBlock *blk, Lyst eidReferences, char *blockData)" 4
.IX Item "int serializeExtBlk(ExtensionBlock *blk, Lyst eidReferences, char *blockData)"
Constructs an RFC5050\-conformant serialized representation of this extension
block in blk\->bytes.  Returns 0 on success, \-1 on an unrecoverable system
error.
.IP "void suppressExtensionBlock(ExtensionBlock *blk)" 4
.IX Item "void suppressExtensionBlock(ExtensionBlock *blk)"
Causes \fIblk\fR to be omitted when the bundle to which it is attached is
serialized for transmission.  This suppression remains in effect until
it is reversed by \fIrestoreExtensionBlock()\fR;
.IP "void restoreExtensionBlock(ExtensionBlock *blk)" 4
.IX Item "void restoreExtensionBlock(ExtensionBlock *blk)"
Reverses the effect of \fIsuppressExtensionBlock()\fR, enabling the block to
be included when the bundle to which it is attached is serialized.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIbp\fR\|(3)