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 +}