
diff -r 000000000000 -r 2b3e5ec03512 doc/plugin-architecture/decision-interface.tex
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/plugin-architecture/decision-interface.tex	Thu Apr 21 14:57:45 2011 +0100
@@ -0,0 +1,1018 @@
+\subsection{Decision Plane Interface}
+\label{sec:dpintf}
+
+This subsection describes the messages between the Decision Plane (DP) and
+the Bundle Protocol Agent (BPA). It describes the parameters of each message
+and their semantics.
+
+This interface assumes that most of the routing and forwarding related
+{\em control} (i.e. decision making) resides in the DP. In
+particular, the ``forwarding table'' is in the DP, and therefore there
+is no need for route- or next-hop-related information to flow across
+this interface.  The DP computes the next hop and issues a command
+(request) to the BPA to send a particular bundle to a particular (next
+hop) endpoint.
+
+This interface is based on the current DTN2 implementation as implicitly
+documented in \cite{MITRE-IF}
+and extends that interface, both with new messages and with more parameters
+for a message. We have strived to retain the parameter list and the set
+of methods as close as possible to current DTN2 implementation.
+In each message description, we include an item called ``DTN2 $\Delta$''
+($\Delta$ = Difference) which says what the change is relative to
+\cite{MITRE-IF}, and refers to the current DTN2 implementation.
+
+We note that this is a ``semantic'' interface, that is, we expect it to
+be specifying the kinds of things that go across and their meanings,
+not necessarily at a level necessary for implementation. We expect, though,
+that an implementation-level specification (e.g., a C++ header file) can 
+be generated easily enough from this.
+
+All messages are assumed to be transparently reliably delivered. 
+
+All parameters are assumed to be ``required'' unless specifically
+noted to be ``optional'' (Opt).
+
+\subsubsection{Parameter Types}
+
+In order to describe the interface succinctly, we define a few commonly used
+complex parameter types.
+
+The main change over~\cite{MITRE-IF} is the introduction of the Global
+Bundle or Fragment ID (GBOF-ID), which uniquely identifies a bundle
+or fragment globally. The name change is to emphasize two things:
+first, that it is a {\em global id} (distinct from any local
+sequence-number-based identifiers generated at each node), and that it
+identifies either a bundle or a fragment.
+
+\begin{verbatim}
+
+GBOF ID                 := [sourceEID, timestamp, isFragment,
+                           fragment-length, frgmtOffset]
+Link ID                 := Unique string identifying a link
+Link Attributes         := [type, state, peerEID, is-reachable, is-usable,
+                           howReliable, howAvailable, reactive-frag-enabled,
+                           underlayAddress, clName,
+                           all-CLA-specific-link-attributes]
+Link Config Parameters  := A set of the following attributes:
+                           is-usable, reactive-frag-enabled, underlayAddress,
+                           configurable-CLA-specific-link-attributes
+ContactAttributes       := [startTime, duration, bps, latency, pktLossProb,
+                           LinkAttributes]
+custodySignalAttributes := [adminType, adminFlags, succeeded, reason,
+                           originalFragOffset, origFragLength,
+                           custodySignalSec, custodySignalUsec,
+                           originalCreationSec, originalCreationUsec,
+                           originalSourceEID]
+\end{verbatim}
+
+Parameter types used in current DTN2~\cite{MITRE-IF} are slightly
+different in some cases and shown below as a reference for the DTN2
+signature given in each message description below.
+
+\begin{verbatim}
+
+bundle                   := [source, dest, custodian, replyto, payload]
+linkAttributes           := [name, type, state, nextHop, reliable(yes/no),
+                            clName]
+linkType                 := [clInfo, linkAttributes]
+contactAttributes        := [startTimeSec, startTimeUsec, duration, bps, 
+                            latency, link]
+custodySignalAtttributes := [adminType, adminFlags, succeeded, reason,
+                            originalFragOffset, origFragLength,
+                            custodySignalSec, custodySignalUsec,
+                            originalCreationSec, originalCreationUsec,
+                            originalSourceEID]
+\end{verbatim}
+
+
+\subsubsection{Event Messages}
+\label{sec:DP-EventMessages}
+
+The event primitives are triggered by the BPA to notify the DP when a 
+reportable event occurs.\\[1em]
+
+
+\method{EventBundleReceived(GBOF-ID, DestEID, ExpiryTime, Custodian, ReplyTo, BytesReceived, [PreviousHopEID])}
+{
+\metP
+    {\em GBOF ID}: Identifies the bundle or fragment that was received.\\
+    {\em Destination EID}: The destination for the bundle.\\
+    {\em Expiry time}: Time (using common local clock) at which the
+    bundle will expire.\\
+    {\em Custodian}: EID of the current custodian of the bundle.\\
+    {\em ReplyTo}: EID same as the reply-to field in the bundle header.\\
+    {\em Bytes received}: Total number of bytes in the bundle payload, 
+    including headers.\\
+    {\em Previous Hop EID (Opt)}: The node from which this bundle was most 
+    recently sent.\\
+
+
+\metD
+    This is sent by the BPA to the DP whenever a bundle is received.
+    The bundle payload itself is retained by the BPA (perhaps in persistent
+    store) and the above parameters are sent. We note that the parameters
+    constitute only a subset of the information available about the received
+    bundle. In the case that the DP requires bundle information not contained
+    in the event, it is expected to use the Query/Report message interface
+    (refer to section~\ref{sec:DP-QueryReportMessages}).
+
+    The expected action from the DP is to decide whether to re-send
+    the bundle and if so how. If it needs to be sent, a sendBundle
+    request is made sometime in the future referring to the GBOF-ID
+    received in the EventBundleReceived message. The Destination EID is
+    used to determine a suitable ``next-hop''. The expiry
+    time may be used to prioritize amongst pending bundles
+    (e.g. sending soon-to-expire bundles first).
+
+    The previous hop EID is optionally indicated to help DP processing, for
+    instance, in flooding-like schemes. It is optional and not mandatory 
+    because it might not always be available (e.g. a bundle that arrives on
+    a USB stick with no previous hop block).
+
+\metM
+    DTN2 Params: (bundle, source, bytesReceived).\\ 
+    Remarks: The specified parameters are a strict superset of the DTN2
+    parameters. The additional parameters
+    (expiry time, previous hop) will help diversify the class of
+    routing algorithms possible.
+
+\metR
+    EventBundleTransmitted \\
+    RequestSendBundle
+}
+
+\method{EventDataTransmitted(GBOF-ID, LinkID, TotalBytesSent, TotalBytesSentReliably)}
+{
+\metP
+    {\em GBOF ID}: Identifies the bundle or fragment that was transmitted.\\
+    {\em Link ID}: Identifies the link over which it was transmitted.\\
+    {\em Total bytes sent}: Number of bytes of data (including headers)
+    transmitted.\\
+    {\em Total bytes sent reliably}: Number of bytes of data (including
+    headers) sent reliably. This could be different from total bytes sent
+    if there were no ACKs received for some part of the data.
+
+\metD
+    [Note: The event name has been changed from EventBundleTransmitted
+    to better reflect the semantics]
+    This is generated by the BPA whenever a bundle or a part of a
+    bundle is transmitted successfully. The GBOF ID identifies the
+    bundle or fragment sent (and if it was fragmented, the subsequent
+    fragments currently get different GBOF IDs).
+    If the ``total bytes sent'' is less than the payload
+    plus header size of the bundle, the DP infers that the bundle has
+    been reactively fragmented. The DP may determine whether or not the
+    whole bundle has been sent as follows: the source EID and timestamp
+    uniquely identify the original bundle, and each fragment identifies
+    the range of this bundle that it covers (via the offset/length). With
+    this, the DP can match a set of fragments to an original bundle.
+     However, not all of the bytes need have been sent
+    {\em reliably} for this event. The number of bytes sent unreliably
+    is equal to ``total bytes sent'' minus ``total bytes sent
+    reliably'' and is assumed to be at the tail (suffix) of the
+    bundle/fragment.  No action is expected from DP apart from state
+    changes regarding the disposition of the identified bundle, and
+    perhaps resending the bundle if not all bytes were sent reliably.
+    
+\metM
+    DTN2 Params: (bundle, contact, bytesSent, bytesReliablySent)\\
+    Remarks: The main difference is the use of Link ID rather than contact, 
+    but the former is a superset of the latter and this only generalizes the
+    parameter. Further, the DP typically does not need to know the contact,
+    since it already knows it from the Link ID. Also, the name of the
+    event has been changed.\footnote{New name due to M. Demmer, in feedback
+    to specification.}
+    
+\metR
+    EventBundleReceived\\
+    RequestSendBundle\\
+    RequestInjectBundle
+}
+
+%\method{EventBundleTransmitFailed(GBOF-ID, LinkID, FailureReason)}
+%{
+%\metP
+%    {\em GBOF-ID}: Identifies the bundle whose transmission failed.\\
+%    {\em Link ID}: Identifies the link on which transmission failed.\\
+%    {\em Failure Reason}: Code indicating reason for failure.
+%
+%\metD
+%    This event is generated when the BPA is asked to send a bundle
+%    (for instance, by a call to RequestSendBundle), and is unable to send
+%    any part of the bundle.  Typically (and in the current version of
+%    the code), this happens when reactive fragmentation is turned off
+%    and the contact goes down.  It also happens (in the current
+%    version) when a link is closed---this event is generated for each
+%    bundle that is queued on the link that was closed. Upon receipt of
+%    this event the DP will typically resend the bundle.
+%
+%\metM
+%    DTN2 Params: (bundle, contact)\\
+%    Remarks: Our parameters are a strict superset of the DTN2  parameters. 
+%
+%
+%\metR
+%    EventBundleTransmitted\\
+%    RequestSendBundle\\
+%    RequestInjectBundle
+%}
+
+\method{EventBundleDelivered(GBOF-ID, SourceEID)}
+{
+\metP
+    {\em GBOF ID}: Identifies the bundle or fragment delivered.\\
+    {\em Source EID}: Identifies the originator of the bundle.
+
+\metD
+    This event is generated when the node is a member of the destination 
+    endpoint. The DP typically uses this event to note that this is 
+    the ``final'' destination and hence no forwarding is required. It may
+    also use this event to perform purging of duplicate bundles in the network.
+
+\metM
+    DTN2 Params: (bundle, source)\\
+    Remarks: No noteworthy difference.
+
+\metR
+    EventBundleReceived\\
+    EventBundleTransmitted
+}
+
+
+\method{EventBundleExpired(GBOF-ID)}
+{
+\metP
+    {\em GBOF ID}: Identifies the bundle whose lifetime has expired.
+
+\metD
+    This event is generated when the lifetime expiration of the identified
+    bundle occurs. It is assumed that the bundle is automatically
+    deleted by the BPA. The DP is not expected to have any action, although
+    it will probably need to clean up state regarding the bundle.
+
+\metM
+    DTN2 Parameters: (bundle)\\
+    Remarks: No noteworthy difference.
+
+\metR
+    None
+}
+
+\method{EventBundleSendCancelled(GBOF-ID, LinkID)}
+{
+\metP
+    {\em GBOF ID}: Identifies the bundle whose sending was canceled.\\
+    {\em Link ID}: Identifies the link for which the bundle send was
+    canceled.
+
+\metD
+    This event is sent when a bundle that was previously requested to be 
+    sent using RequestSendBundle is canceled upon a subsequent request of 
+    RequestCancelBundleSend. The DP uses this as a positive confirmation of its
+    request
+
+\metM
+    DTN2 does not have this event.
+
+\metR
+    RequestSendBundle\\
+    RequestCancelBundleSend
+}
+
+
+\method{EventCustodySignal(GBOF-ID, CustodySignalAttributes)}
+{
+\metP
+    {\em GBOF ID}: Identifies the bundle or fragment for which a custody signal
+    has been sent.\\
+    {\em CustodySignalAttributes}: This is a complex type defined earlier and  
+    contains the fragment info, creation and signal timestamps, and whether
+    or not custody transfer succeeded and if not the reason.
+
+\metD
+    A custody signal indicates successful or unsuccessful transfer of
+    custody~\cite{BP-ID}. This event is generated at the current custodian
+    when it receives a custody signal from another endpoint. An unsuccessful
+    custody transfer may prompt the DP to look for a different next hop,
+    based on the reason code.
+
+\metM
+    DTN2 Params: (CustodySignalAttributes)\\
+    Remarks: Our signature is similar but pulls out GBOF ID redundantly
+    for uniformity and ease of coding the DP.
+
+\metR
+    EventCustodyTimeout
+}
+
+
+\method{EventCustodyTimeout(GBOF-ID)}
+{
+\metP
+    {\em GBOF ID}: Identifier of the bundle or fragment whose custody has
+    timed out.
+
+\metD
+    This event is generated when no custody signal was received within
+    a configured time. The DP might use this to forward the bundle to
+    a different endpoint.
+
+\metM
+    DTN2 Params: (bundle, linkType)\\
+    Remarks: The DTN2 interface has an extra parameter, namely linkType. 
+    The link parameter records the adjacent link on which a bundle was
+    originally sent. This information is meant for the bundle's forwarding
+    log, and not really necessary for the DP-BPA interface.\footnote{Based
+    on email from J. Bush.}
+
+\metR
+    EventCustodySignal
+
+}
+
+Until now, we have looked at event messages related to bundle handling. We now
+switch to events regarding link dynamics.
+
+\method{EventLinkCreated(LinkID, LinkAttributes, Reason)}
+{
+\metP
+    {\em Link ID}: Name of  the link that was created. Should be
+    used as a handle for all future references to that link.\\
+    {\em Link Attributes}: A complex type defined earlier that gives
+    more information about the link. This includes the type
+    (scheduled/discovered etc.), its state (open, available, unavailable etc),
+     the peer EID on the
+    other end of the link, the convergence layer name, and optionally 
+    an indication of how reliable and how available it is expected to be.
+    The complete list is preliminarily same as in~\cite{MITRE-IF}.\\
+    {\em Reason}: How the link was created. E.g, user, convergence layer, etc.
+    A list of current reason codes with meanings is given in~\cite{MITRE-IF}.
+
+\metD
+    This message is the first event to be generated with regards to a
+    new link. The new link may be created by the user, by the
+    convergence layer or any other means. The BPA names this link and
+    gives some of the attributes of this link. The state of the link
+    upon creation may be dependent on the type of link. Currently, the
+    initial state is AVAILABLE for on-demand, scheduled, and static
+    links, and UNAVAILABLE for discovered and opportunistic
+    links. Upon receipt of this event, the DP is expected to
+    initialize data structures for this link in anticipation of the
+    contact becoming available some time in the future, if not
+    already.
+
+\metM
+    DTN2 Params: (linkType, Reason)\\
+    Remarks: After expanding the complex types, there are no noteworthy
+    differences between DTN2 and specified parameters here. 
+
+\metR
+    EventLinkDeleted\\
+    EventLinkAvailable\\
+    EventLinkOpened\\
+    EventLinkAttributeChange\\
+    RequestAddLink
+}
+
+
+\method{EventLinkDeleted(LinkID, LinkAttributes, Reason)}
+{
+\metP
+    {\em Link ID}: Identifies the deleted link.\\
+    {\em Link Attributes}: Lists the attributes.\footnote{Not convinced this is
+    needed since the link is going away, but kept it in deference to DTN2.}\\
+    {\em Reason}: Why the link was deleted. A list of current reason codes 
+    with meanings is given in~\cite{MITRE-IF}.
+
+\metD
+    This event is generated when a link is deleted. The DP is expected to
+    clean up the data structures associated with the link but no other
+    action is needed. NOTE: The current code does not handle link deletions.
+    This message has been specified in anticipation of the code being able
+    to  handle it some time in future. It should be implemented after such
+    accommodations.
+
+\metM
+    DTN2 Params: (linkType, Reason)\\
+    Remarks: After expanding the complex types, there are no noteworthy
+    differences between DTN2 and specified parameters here. 
+
+\metR
+    EventLinkCreated
+}
+
+\method{EventLinkAvailable(LinkID, LinkAttributes, Reason)}
+{
+\metP
+    {\em Link ID}: Identifies the link that has become available.\\
+    {\em Link Attributes}: More info about the link.\\
+    {\em Reason}: Why the link became available.
+
+\metD
+    This event message is sent when a link that was unavailable earlier
+    now becomes available for use.  The Link Attributes contains the
+    latest value of the link attributes. Upon
+    receipt of this event, the DP might 
+    try and open the link and/or start using the link in its routing
+    computations. This event currently pertains only to on-demand,
+    static, and scheduled links.
+
+\metM
+    DTN2 Parameters: (linkType, reason)\\
+    Remarks: After expanding the complex types, there are no noteworthy
+    differences between DTN2 and specified parameters here. 
+
+\metR
+    EventLinkCreated\\
+    EventLinkUnavailable\\
+    RequestOpenLink
+
+}
+
+\method{EventLinkUnavailable(LinkID, LinkAttributes, Reason)}
+{
+\metP
+    {\em Link ID}: Identifies the link that has become unavailable.\\
+    {\em Link Attributes}: More info about the link.\\
+    {\em Reason}: Why the link became unavailable.
+
+\metD
+    This event message is sent when a link that was previously available
+    now becomes unavailable. The Link
+    Attributes contains the latest value of the link attributes.
+    Upon receipt of this event, the DP might mark the link 
+    as ``down'' and trigger updates to inform other nodes to not use this
+    link.
+
+\metM
+    DTN2 Parameters: (linkType, reason)\\
+    Remarks: After expanding the complex types, there are no noteworthy
+    differences between DTN2 and specified parameters here.
+
+\metR
+    RequestCloseLink\\
+    EventLinkAvailable
+}
+
+\method{EventLinkOpened(LinkID, ContactAttributes)}
+{
+\metP
+    {\em Link ID}: Identifies the link which was just opened.\\
+    {\em Contact Attributes}: Gives info about the nature of communications
+    with this contact---when it starts and stops, data rate, latency, etc.
+
+\metD
+    This event message is sent when a link is opened, either upon request
+    by the DP, or the operator (typical for on-demand and scheduled links)
+    or by the CLA automatically discovering a peer (for discovered and
+    opportunistic links). This event is expected by the DP when it issues
+    a RequestSendBundle, and
+    gives the DP the green signal to go ahead and send bundles to
+    this endpoint. The contact attributes may be used by the DP for
+    scheduling/prioritizing purposes.
+
+\metM
+    DTN2 Params: (contactAttributes)\\
+    Remarks: This is similar to the ContactUpEvent of DTN2. Has been renamed
+    as it better reflects the semantics in the context of this interface. 
+    Modulo this, after expanding the complex types, there are no noteworthy
+    differences between DTN2 and specified parameters.
+
+\metR
+    EventLinkClosed\\
+    EventLinkDeleted\\
+    RequestSendBundle
+
+}
+
+\method{EventLinkClosed(LinkID, ContactAttributes)}
+{
+\metP
+    {\em Link ID}: Identifies the link whose peer endpoint went down.\\
+    {\em Contact Attributes}: Gives info about the nature of communications 
+    with this contact.\footnote{Not convinced this is
+    needed since the contact is going away, but kept it in deference to DTN2.}
+
+\metD
+    This event message is sent when the link is closed. This typically
+    is done by the CLA when it believes that the contact has been down
+    so long that it is not worth keeping the link open. The DP may
+    also explicitly close the link (see RequestCloseLink). The
+    criteria for closing a link may differ depending upon the link
+    type.  The LinkClosed event enables the DP to avoid using this
+    endpoint as a transit endpoint for sending bundles, for example.
+
+\metM
+    DTN2 Params: (contactAttributes)\\
+    Remarks: This is similar to the ContactDownEvent of DTN2. Has
+    been renamed as it better reflects the semantics in the context of
+    this interface. Modulo this, after expanding the complex types,
+    there are no noteworthy differences between DTN2 and specified
+    parameters.
+
+\metR
+    EventLinkOpened
+    RequestCloseLink
+}
+
+    
+\method{EventLinkAttributeChange(LinkID, LinkAttributes, Reason)}
+{
+\metP
+    {\em Link ID}: Identifies the link one of whose attributes has changed.\\
+    {\em Link Attributes}: The latest set of attributes.\\
+    {\em Reason}: A reason for the change.
+
+\metD
+    The message informs the DP of any change in the link attributes,
+    in particular, between creation, availability and contact. For
+    example, when a link becomes available, the set of attributes is
+    updated, but if the attributes change after that, the Link
+    Attribute Change event is generated. Changes in the REACHABILITY
+    and USABILITY flags are also indicated using this event--note
+    that these flags are part of the LinkAttributes complex type.  The
+    DP uses this information to decide whether or not to
+    include/exclude this link from routing considerations based on the
+    new set of attributes.
+
+\metM
+    DTN2 Parameters: DTN2 does not have this message. \\
+    Remarks: This message is most useful in (multi-hop) wireless links 
+    whose properties may change frequently and this may affect routing.
+
+\metR
+    EventLinkCreated\\
+    EventLinkAvailable\\
+    EventLinkOpened\\
+    EventContactAttributeChange
+}
+
+\method{EventContactAttributeChange(ContactEID, ContactAttributes, Reason)}
+{
+\metP
+    {\em Contact EID}: Identifies the contact whose attributes have changed.\\
+    {\em Contact Attributes}: The latest set of attributes for the contact.\\
+    {\em Reason}: A reason for the change.
+
+\metD
+    This message informs the DP of any change in the contact attributes,
+    in particular, after the contact up event has been generated. For
+    example, a contact might go into a very deep fade in a valley and its
+    ``bps'' parameter may drop dramatically. This event serves to inform this
+    to the DP so that routing decisions may be modified accordingly.
+
+\metM
+    DTN2 does not have this message.\\
+    Remarks: This message is most useful in (multi-hop) wireless links
+    whose properties may change frequently and this may affect routing.
+
+\metR
+    EventLinkOpened\\
+    EventLinkAttributeChange
+}
+
+
+\subsubsection{Request Messages}
+\label{sec:DP-RequestMessages}
+
+Request messages are sent by the DP to the BPA. They are ``actions''
+that the DP wants the BPA to perform. Requests do not have an explicit
+associated response. Instead, some combination of event messages and
+timeouts are used to confirm that the requests have been acted
+upon.\\[1em]
+
+\method{RequestOpenLink(LinkID)}
+{
+\metP
+    {\em Link ID}: Identifies the link that the DP wants opened.\\
+
+\metD
+    This message is currently meant for on-demand links only. It is
+    assumed that the link has been created and a EventLinkCreated
+    message was generated by the BPA and received by the DP. The Link
+    ID used here is the same as the Link ID given in the
+    EventLinkCreated interface.  The DP makes this request when it
+    wants to send a bundle to a peer EID on this link, and expects an
+    EventLinkAvailable message in response.  The link is kept open
+    until a RequestCloseLink is issued until deemed idle (see
+    section~\ref{sec:linktypes}).
+
+\metM
+    DTN2 Parameters: (link)\\
+    Remarks: We have two additional parameters, attributes and duration. 
+    This will give more flexibility in how to manage the link. 
+
+\metR
+    EventLinkAvailable\\
+    RequestCloseLink
+}
+
+\method{RequestCloseLink(LinkID)}
+{
+\metP
+    {\em Link ID}: Identifies the link that the DP wants closed.
+
+\metD
+    This request closes a link that the DP is no longer interested in
+    keeping open. However, the DP cannot assume that the BPA actually closed
+    the link. The BPA may not close the link, for example, if other
+    DP processes had wanted the link open. If the DP needs confirmation
+    (it may not, typically, need it), then it should wait for the
+    Link Unavailable event.
+
+\metM
+    DTN2 does not have this message.
+
+\metR
+    RequestOpenLink\\
+    EventLinkUnavailable
+
+}
+
+\method{RequestAddLink(LinkType, PeerEID, CLAName, [LinkConfigParameters])}
+{
+\metP
+    {\em Link Type}: The type of link being added.\\
+    {\em Peer EID}: The endpoint ID for the peer of the link being added.\\
+    {\em CLA Name}: The CLA the link being added should use.\\
+    {\em Link Config Parameters (Opt)}: Describes the link to add. 
+
+\metD
+    This request is meant for the case when the DP knows about certain links
+    that the CLA does not and would like to have them
+    added. The request can supply link attributes. After issuing this,
+    the DP waits for a LinkCreated event to be able to use the link. This
+    event is the confirmation that the request was satisfied.
+
+\metM
+    DTN2 does not have this request.
+
+\metR
+    EventLinkCreated
+}
+
+\method{RequestDeleteLink(LinkID)}
+{
+\metP
+    {\em Link ID}: Identifies the link to be deleted. Taken from the
+    EventLinkCreated call.
+
+\metD
+    This request is for deleting links that the DP added using the
+    RequestAddLink command. The DP should only delete links that it added,
+    and thus, the LinkID should only identify a link that was created
+    due to a RequestAddLink call from the DP. The EventLinkDeleted confirms
+    that the request went through.
+
+\metM
+    DTN2 does not have this request.
+
+\metR
+    RequestAddLink \\
+    EventLinkCreated \\
+    EventLinkDeleted
+}
+    
+\method{RequestReconfigureLink(LinkID, LinkConfigParameters)}
+{
+\metP
+    {\em Link ID}: Identifies the link to be reconfigured.\\
+    {\em Link Config Parameters}: The new set of attributes.
+
+\metD
+    Link parameters may be changed after creation time with this
+    request. Changes are applied immediately where it makes sense, even if the
+    link is open. The Link Config Parameters parameter updates link attributes.
+    The EventLinkAttributeChange confirms that this request went through.
+
+\metM
+    DTN2 does not have this request.
+
+\metR
+    RequestAddLink\\
+    RequestDeleteLink\\
+    EventLinkAttributeChange
+}
+
+    
+\method{RequestSendBundle(GBOF-ID, LinkID, ForwardAction, [FragmentSize, FragmentOffset, ExtensionBlock])}
+{
+\metP
+    {\em GBOF ID}: Identifies the bundle that the DP wants sent.\\
+    {\em Link ID}: Identifies the link over which the DP wants the bundle
+    sent.\\
+    {\em Forward Action}: One of ``forward to one next hop'', ``forward a
+    copy''\\
+    {\em Fragment Size (Opt)}: To support proactive fragmentation, this field 
+    specifies that only this many bytes of the bundle ought to be sent.
+    Optional parameter.\\
+    {\em Fragment Offset (Opt)}: To support proactive fragmentation, this 
+    field specifies the offset of the size above.\\
+    {\em Extension Block (Opt)}: To be attached after the bundle protocol 
+    header, contains DP-specific information to be piggybacked to DPs in other
+    endpoints. Optional parameter.
+
+\metD
+    As discussed earlier, received bundles are retained by the BPA, with
+    the event giving some important information to the DP. RequestSendBundle
+    message identifies a retained bundle using the GBOF ID that was given
+    in the BundleReceived event and asks it to be sent over a link
+    identified using a Link ID that was given to it in the Link Created
+    event. The Forward Action further qualifies this transmission, in
+    particular whether it wants a copy retained for further forwarding
+    (as may be done in Epidemic Routing). 
+
+    If the Fragment Size field is specified, then the BPA is expected
+    to fragment the specified bundle and send only the fragment. The
+    BPA retains the rest of the bundle awaiting further send or
+    fragment-and-send instructions from the DP.  The extension block
+    is created by the DP and is requested to be attached verbatim
+    after the BP header. This facility is useful for protocols that
+    require control information to be piggybacked on bundles
+    (e.g.~\cite{MaxProp}).
+
+    A BundleTransmitted event following this request serves to confirm
+    that the action was indeed performed. Note that there is no event for
+    the failure of bundle transmission (such an event was there in a previous
+    version and has been removed). Therefore, the DP is responsible for
+    using some method to decide whether to resend the bundle. For example,
+    it could use a timeout and then cancel the sending of the previous 
+    bundle, and if appropriate, resend it on another link. 
+
+
+\metM
+    DTN2 Params: (bundleId, link, forwardAction)\\
+    Remarks: We have two extra parameters, both optional---the fragment
+    size, to support proactive fragmentation, and the extension 
+    block, to support more sophisticated routing protocols.
+
+\metR
+    EventBundleTransmitted\\
+    RequestCancelSendBundle
+}
+
+\method{RequestBroadcastSendBundle(GBOF-ID, ForwardAction, [FragmentSize, FragmentOffset, ExtensionBlock])}
+{
+\metP
+    {\em GBOF ID}: Identifies the bundle that the DP wants sent.\\
+    {\em Forward Action}: One of ``forward to one next hop'', ``forward a
+    copy''\\
+    {\em Fragment Size (Opt)}: To support proactive fragmentation, this field
+    specifies that only this many bytes of the bundle ought to be sent.
+    Optional parameter.\\
+    {\em Fragment Offset (Opt)}: To support proactive fragmentation, this
+    field specifies the offset of the size above.\\
+    {\em Extension Block (Opt)}: To be attached after the bundle protocol
+    header, contains DP-specific information to be piggybacked to DPs in other
+    endpoints. Optional parameter.
+
+\metD
+    This is relevant for broadcast channels only, not point-to-point. In
+    this case, a node might wish to simply transmit the bundle without having
+    it be intended for anyone in particular. Such broadcasting is a key part
+    of MANET operation, one of the network types envisaged for DTNs. Unlike
+    a RequestSendBundle to each and every link (which may be considered a
+    broadcast too), the key here is that there is no link specified---indeed,
+    the node may not even know which other nodes receive this. Intended uses
+    are for bundle flooding, epidemic routing and transmitting DP probes.
+
+    The field semantics are identical to that of RequestSendBundle. 
+
+    A BundleTransmitted event following this request serves to confirm that
+    the action was indeed performed.
+
+\metM
+    DTN2 does not have this message\\
+
+\metR
+    RequestSendBundle\\
+    EventBundleTransmitted\\
+}
+
+\method{RequestCancelBundleSend(GBOF-ID, LinkID)}
+{
+\metP
+    {\em GBOF-ID}: Identifies the bundle whose sending needs to be canceled.\\
+    {\em Link ID}: Identifies the link for which the bundle sending must be
+    canceled.
+
+\metD
+    After having issued a RequestSendBundle, the DP may wish to retract it,
+    if possible. This could happen for instance, if the transmission failed
+    and the DP wants to try another bundle, or if it found out that the
+    bundle has been delivered and does not need to be sent anymore, or  
+    for other reasons. 
+
+\metM
+    DTN2 Message: CancelBundleRequest(bundleId, link)\\
+    Remarks: We presume the CancelBundleRequest is to cancel the {\em sending}
+    of a bundle and not something else, like deleting a bundle. The ``link''
+    parameter is not present in our interface for reasons mentioned above.
+
+\metR
+    RequestSendBundle\\
+    EventBundleSendCancelled
+}
+
+\method{RequestInjectBundle(SourceEID, DestEID, payload, [ReplyTo, Custodian, Priority, Expiration, Forward Action])}
+{
+\metP
+    {\em Source EID}: The EID of this DP/router (the one that is
+    injecting the bundle).\\
+    {\em Dest EID}: Identifies the endpoint, typically a peer, for which 
+    the injected bundle is meant.\footnote{Can a bundle be injected for a
+    non-peer endpoint?}\\
+    {\em Payload}: The information content (data part) of the bundle. Base64
+    encoded~\cite{MITRE-IF}\\
+    {\em ReplyTo (Opt)}: Where delivery notification must be sent.\\
+    {\em Custodian (Opt)}: Current custodian.\\
+    {\em Priority (Opt)}: The priority assigned to this bundle.\\
+    {\em Expiration (Opt)}: The expiration time of this bundle.\\
+    {\em Forw Action (Opt)}: Forwarding action type as in RequestSendBundle.
+
+\metD
+    An injected bundle is meant for peer DP(s). We envisage that DP
+    will subscribe to a well known endpoint like {\tt dtn://ext.dp}
+    and injected bundles will have the destination EID set as {\tt
+    peer-EID/ext.dp/foo} where {\tt foo} is a service tag
+    (e.g. bbn-algo-4). This message only injects a bundle, does not
+    actually cause it to be sent. Sending of an injected bundle should
+    be done using the RequestSendBundle command.  An injected bundle
+    undergoes pretty much the same kinds of operations as a
+    ``regular'' bundle. A EventBundleTransmitted message from the BPA
+    will serve to confirm that the injected bundle has been
+    transmitted.\\
+
+    The DP can also, optionally, specify the other fields that go into
+    the BP header, namely the ReplyTo, Custodian, Priority and
+    Expiration.\footnote{This is not mandatory because the control
+    protocol using the injected bundle usually has a way to get rid of
+    the injected (control) bundles once their utility is
+    over. E.g. using sequence numbers, timestamps etc. So there is no
+    need to additionally mandate an expiration field. However, for control
+    protocols that don't have this facility, this is available as an option.}
+     BPA uses defaults
+    in much the same way it treats application bundles.
+
+\metM
+    DTN2 Params: (source,destination,replyto,custodian,link,fwdAction,priority,expiration,payload)\\
+    Remarks: No noteworthy difference.
+
+\metR
+    RequestSendBundle\\
+    EventBundleTransmitted\\
+}
+
+\method{RequestDeleteBundle(GBOF-ID)}
+{
+\metP
+    {\em GBOF-ID}: Identifies the bundle that the DP wants deleted.
+
+\metD
+    Recall that our architecture calls for the BPA to retain control of
+    the bundle itself (storing etc.) while passing relevant parameters
+    to the DP. If the DP determines that a bundle no longer need be
+    stored, persistently or otherwise, it issues this command to delete
+    the bundle. The DP may want to delete the bundle if it is informed
+    through peer-DP mechanisms that a copy of the bundle was delivered.  
+    This request is useful for replication oriented forwarding, for
+    example, Epidemic Routing. There is no event for confirming that
+    the bundle was deleted. 
+
+\metM
+    DTN2 does not have this request message. 
+
+\metR
+    RequestSendBundle
+}
+
+\method{RequestSetCLAParams(Parameters)}
+{
+\metP
+    {\em Parameters}: A list of (key, value) pairs.
+
+\metD
+    This is a ``pass-through'' request to the BPA to set the convergence
+    layer adapter parameters. The BPA is expected to invoke the message to
+    set CLA parameters using the (key, value) pairs in Parameters. The key
+    identifies the name of the parameter and the value is what the 
+    CLA is supposed to set that parameter to.
+
+\metM
+    DTN2 does not have this request. 
+
+\metR
+    None
+}
+
+\subsubsection{Query/Report Messages}
+\label{sec:DP-QueryReportMessages}
+
+Query/Report messages consist of a set of ``paired'' messages---a Query
+message from the DP to the BPA requesting certain information from the BPA and
+a report message for that query from the BPA to the DP delivering the
+requested information, if possible. Unlike the Request-Event messages which
+are only loosely tied, there is a tighter coupling between query and report,
+in particular a report identifies which query is being responded to.
+
+We have separate query/report messages for bundle and link. As will be
+apparent after reading the structure of the messages, there really isn't
+a need to separate it, but we have done so in deference to DTN2 which
+had it separate.\\[1em]
+
+\method{QueryBundleAttributes(QueryID, QueryParams)}
+{
+\metP
+    {\em  QueryID}: Identifies the query (a handle) to tie the report.\\
+    {\em  QueryParams}: A list of keys. The key identifies which information
+    object is asked for. A list of key types, mutually agreed upon by DP and
+    BPA to be defined somewhere.\footnote{Not currently included in this
+    document.}
+
+\metD
+    This query is for getting the value of any subset of a number of
+    pre-defined bundle attributes, including extension block contents, 
+    including location and contents of injected (control)  bundle payload. 
+    A unique query id is passed and a
+    report message containing the query id is awaited. The report contains
+    the requested information (key, value) pairs (see below).
+
+\metM
+    DTN2 has a bundleQuery message but its parameters are not defined.
+
+\metR
+    ReportBundleAttributes
+}
+
+\method{ReportBundleAttributes(QueryID, ReportParams)}
+{
+\metP
+    {\em QueryID}: Identifies which query is being responded to.\\
+    {\em ReportParams}: A list of (key, value) pairs.
+
+\metD
+    This message is a response to a query and reports the latest value
+    of the bundle attributes that were queried for.  The query id ties
+    the report to the query. The ReportParams contains (key, value)
+    pairs, where each key is taken from the list of keys supplied with
+    the corresponding query, and the value is the value of whatever is
+    requested for by the key.
+
+\metM
+    DTN2 Message: bundleReport(bundleType)\\
+    Remarks: The difference is that the specified message is more generalized,
+    DTN2 message is a specific key, value pair, one which dumps
+    whatever is known about the bundle.
+
+\metR
+    QueryBundleAttributes
+}
+
+\method{QueryLinkAttributes(QueryID, LinkID, QueryParams)}
+{
+\metP
+    {\em  QueryID}: Identifies the query (a handle) to tie the report.\\
+    {\em  Link ID}: Identifies the link whose attributes are sought.\\
+    {\em  QueryParams}: A list of keys. The key identifies which information
+    object is asked for. A list of key types, mutually agreed upon by DP and
+    BPA is defined somewhere.\footnote{Again probably not as part of the arch
+    document?}
+
+\metD
+    This query is for getting the value of any subset of a number of
+    pre-defined link attributes. A unique query id is passed and a
+    report message containing the query id is awaited. The report contains
+    the requested information (key, value) pairs (see below).
+
+\metM
+    DTN2 has a linkQuery but its parameters are not defined.
+
+\metR
+    ReportLinkAttributesReport
+
+}
+
+\method{ReportLinkAttributes(QueryID, ReportParams)}
+{
+\metP
+    {\em QueryID}: Identifies which query is being responded to.\\
+    {\em ReportParams}: A list of (key, value) pairs.
+
+\metD
+    This message is a response to a query and reports the latest value
+    of the link attributes that were queried for.  The query id ties
+    the report to the query. The ReportParams contains (key, value)
+    pairs, where each key is taken from the list of keys supplied with
+    the corresponding query, and the value is the value of whatever is
+    requested for by the key.
+
+\metM
+    DTN2 Message: linkReport(linkType)\\
+    Remarks: The difference is that the specified message is more generalized,
+    DTN2 message is a specific key, value pair, one which dumps
+    whatever is known about the link.
+
+\metR
+    QueryLinkAttributes
+}




