Bundle API 0.2

7/30/2019 Bundle API 0.2

1/28

1

Applications Programming Interface for the

Bundle Daemon Reference Implementation

Version 0.2

Keith Scott, Ed.

March 3, 2003

Delay Tolerant

Networking

7/30/2019 Bundle API 0.2

2/28

2 Bundling AP

2

Contents

1 Bundling API 11.1 Introduction ................................................................................................................................. 11.2 Bundling Philosophy ................................................................................................................... 21.3 Installation................................................................................................................................... 21.4 Licenses ....................................................................................................................................... 21.5 Sample Applications.................................................................................................................... 4

2 File Descriptions 62.1 BDRI API and Remote Procedure Calls...................................................................................... 62.2 Include Files ................................................................................................................................ 62.3 Data Structure Definitions...........................................................................................................62.4 Functions ..................................................................................................................................... 7

3 Sending Bundles 133.1 Step 0: Variable declarations..................................................................................................... 133.2 Step 1: Open bundle agent connection ...................................................................................... 133.3 Step 2: Generate the source and destination tuples ................................................................... 133.4 Step 4: Generate a bundle spec.................................................................................................. 143.5 Step 5: Call one of the send_bundle_XXX functions................................................................ 143.6 Step 6: Close the RPC Connection to the bundle agent............................................................. 143.7 Sample Code snd_bundle.c..................................................................................................... 15

4 Receiving Bundles 204.1 Step 0: Variable and function declarations................................................................................ 204.2 Step 1: Open a connection to the bundle agent.......................................................................... 20

4.3 Step 2: Create the destination tuple ........................................................................................... 204.4 Step 3: Register the destination tuple with the bundle agent..................................................... 204.5 Step 4: Receive Bundles............................................................................................................204.6 Sample Code rcv_bundle.c..................................................................................................... 21

5 References 26

7/30/2019 Bundle API 0.2

3/28

Chapter 1

1 Bundling API

1.1 Introduction

Delay Tolerant Networking, and its supporting protocol known as bundling, is a store-and-

forward, message-based communications architecture that operates in the face of long delays and

intermittent connectivity. The store-and-forward nature of bundling differs from that of the

Internet Protocol (IP) in that bundling explicitly accounts for situations when no path to thedestination exists (network partitioning). Most IP implementations fail when the network

becomes partitioned, immediately returning ICMP Host Unreachable or Network Unreachable

errors when no forward progress can be made. In bundling, messages (bundles) may be queuedat bundle routers waiting for an outbound path to become available. Bundling sits at the

application level of the Internet model, and forms an overlay as shown in Figure 1.

Figure 1: The bundling protocol sits at the application layer of the Internet model.

This document describes the application programming interface (API) to the bundle daemonreference implementation (BDRI). Nodes participating in the bundling protocol are referred to

here as bundle agents or bundle daemons. [1] describes the overall architecture for bundling,

Application Application

Bundle Bundle

Transport Transport Transport TransportNetwork Network Network Network

BundleBundleBundleBundle

An Internet An Internet

7/30/2019 Bundle API 0.2

4/28

2 Bundling AP

2

with a tutorial level overview presented in [2]. [3] contains a detailed description of the bundling

protocol, the protocol bundle agents use to exchange bundles. A separate document will describethe internals of the BDRI, as well as the interface between the BDRI and the mechanisms, called

convergence layers, used to transmit bundles across specific internets.

1.2 Bundling Philosophy

Delay Tolerant Networking captures the concepts of communicating in environments wherethere are extremely long delays and/or intermittent connectivity. In general, delay tolerant

applications are not allowed to make any assumptions about message delivery delays. The

bundling protocol is designed to be non-chatty in its delivery of messages. That is, thebundling protocols attempt to keep the number of round trips required to forward bundles to a

minimum. Applications are expected to do the same. As an example, Internet FTP uses eight

round trips before data starts flowing. Some of these are for TCPs SYN/SYN-ACK exchange,others to get the users username and password. In a long delay environment, eight round trips

might be prohibitive. Thus bundle applications are expected to create fewer (possibly more

complex) messages to accomplish their goals. For example, a bundle FTP client might extract

from the user the file to (send/get), the source and destination locations in the local and remotefile systems, and the users authentication information. Using this method, a file SEND

operation can be achieved in a single bundle.

The bundling protocols provide a custody-transfer-based reliability mechanism. Under custody

transfer, intermediate routers can take custody of bundles. Taking custody of a bundle means

assuming responsibility for delivering that bundle to the destination. In practice this meansstoring a copy of the bundle in case it has to be retransmitted. Nodes that take custody of

bundles can release the retransmission resources once a downstream node accepts custody from

them. The rationale behind custody transfer is twofold. First, end systems with very limited

resources such as sensor nodes or deep-space probes may want to transmit data and then releasetheir retransmission resources as soon as possible. These nodes can request custodial message

transfer and free their resources as soon as a downstream node accepts custody. The second

reason for custody transfer is in response to networks with long-delay links. In these cases,retransmission from the source may take much longer than retransmission from an intermediate

point in the network.

1.3 Installation

Acquire the package

Unpack it (probably some variant of tar xzf dtnri.tgz) Change directory to the top level and type make

1.4 Licenses

The BDRI contains code covered by the GNU General Public License, as well as licenses from

the California Institute of Technology, the Intel Corporation and The MITRE Corporation.

7/30/2019 Bundle API 0.2

5/28

3 Bundling AP

3

1.4.1 GPL

The GPL license applies to those example applications that use the Glade user interface tools.

1.4.2 Intel License/*

* IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.* By downloading, copying, installing or using the software you agree to this

* license. If you do not agree to this license, do not download, install,

* copy or use the software.

*

* Intel Open Source License

*

* Copyright (c) 1996-2002 Intel Corporation. All rights reserved.

*

* Redistribution and use in source and binary forms, with or without

* modification, are permitted provided that the following conditions are met:

*

* Redistributions of source code must retain the above copyright notice,

* this list of conditions and the following disclaimer.

*

* Redistributions in binary form must reproduce the above copyright* notice, this list of conditions and the following disclaimer in the

* documentation and/or other materials provided with the distribution.

*

* Neither the name of the Intel Corporation nor the names of its

* contributors may be used to endorse or promote products derived from

* this software without specific prior written permission.

*

* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''

* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,

* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR

* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE INTEL OR ITS CONTRIBUTORS

* BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;

* OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF

* THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*/

1.4.3 JPL / Caltech License****************************************************************************NO WARRANTY:

DISCLAIMER

THE SOFTWARE AND/OR RELATED MATERIALS ARE PROVIDED "AS-IS" WITHOUT WARRANTYOF ANY KIND INCLUDING ANY WARRANTIES OF PERFORMANCE OR MERCHANTABILITY ORFITNESS FOR A PARTICULAR USE OR PURPOSE (AS SET FORTH IN UCC 23212-2313) ORFOR ANY PURPOSE WHATSOEVER, FOR THE LICENSED PRODUCT, HOWEVER USED.

IN NO EVENT SHALL CALTECH/JPL BE LIABLE FOR ANY DAMAGES AND/OR COSTS,INCLUDING BUT NOT LIMITED TO INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANYKIND, INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS,REGARDLESS OF WHETHER CALTECH/JPL SHALL BE ADVISED, HAVE REASON TO KNOW, ORIN FACT SHALL KNOW OF THE POSSIBILITY.

USER BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF THE SOFTWAREAND/OR RELATED MATERIALS.

7/30/2019 Bundle API 0.2

6/28

4 Bundling AP

4

THIS SOFTWARE AND/OR RELATED MATERIALS MAY BE SUBJECT TO EXPORT CONTROLS,AND THE USER HAS THE RESPONSIBILITY OF COMPLYING WITH ALL APPLICABLE FEDERALEXPORT LAWS AND REGULATIONS.Copyright 2003, California Institute of Technology. ALL RIGHTS RESERVED. U.S.Government Sponsorship acknowledged.

****************************************************************************

1.4.4 MITRE License/****************************************************************************

*

* IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.

* By downloading, copying, installing or using the software you agree to this



*

* Copyright (c) 2002, The MITRE Corporation

* All rights reserved.

*

* Redistribution and use in source and binary forms, with or without* modification, are permitted provided that the following conditions are

* met:

*


* this list of conditions and the following disclaimer. Redistributions

* in binary form must reproduce the above copyright notice, this list of

* conditions and the following disclaimer in the documentation and/or

* other materials provided with the distribution.

*

* Neither the name of The MITRE Corporation nor the names of its



*

* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS

* IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR

* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR

* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,

* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,

* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*

****************************************************************************/

1.5 Sample ApplicationsThe DTNRI distribution contains a number of sample applications. The simplest of these are the

console versions ofsnd_bundle and rcv_bundle. A number of Glade projects are also

included that build GUI test applications. Finally, a version of the CCSDS File DeliveryProtocol (CFDP) that runs over bundles is included.

7/30/2019 Bundle API 0.2

7/28

5 Bundling AP

5

1.5.1 Console Applications

snd_bundle.c Text-based application to send bundles.

rcv_bundle.c Text-based application that receives bundles.

dtncfdp Port of the CCSDS File Delivery Protocol (CFDP) to run over bundling.

1.5.2 Glade Projects

Several of the subdirectories of the apps directory contain Glade projects. Glade is a user

interface building framework. To make any of the Glade projects, change to the top-level project

directory (e.g. SndBundle) and type sh autogen.sh.

SndBundle GUI bundle sending application.

RcvBundle GUI bundle receiving application.

gdtnperf-0.1.0 GUI application that interacts with the bundle agent via a

UDP management interface. gdtnperf graphically displaysinformation about contacts and queue lengths, and is most

useful when the bundle daemon has intermittent contacts.

RcvMote GUI application that receives light-level data from motes and

displays it on screen.

7/30/2019 Bundle API 0.2

8/28

Chapter 2

2 File Descriptions

2.1 BDRI API and Remote Procedure Calls

The application interface to the bundle daemon reference implementation (the code that

implements the bundling protocols as described in [1,2,3]) is via remote procedure calls, or

RPCs. An application wishing to transmit and receive bundles must contain both and RPC client

(to send information to the bundle agent) and an RPC server (to receive responses, includingincoming bundles). This is shown in Figure 2. This chapter describes the data types and

routines provided by the bundle_api.h include file and the libdtn library.

RPC

client

RPC

server

Bundle

Application

Bundle Daemon

RPCclientRPCserver

libdtn

libdtn

Figure 2: Application -- daemon interaction via remote procedure calls.

2.2 Include Files

Bundle applications #include the bundle_api.h header file and link with the libdtn

library.

2.3 Data Structure Definitions

BUNDLE_AGENT Opaque token to the application used to reference a particularbundle agent.

BUNDLE_TUPLE Structure defining a DTN tuple (endpoint identifier). Notethat the actual storage for the tuple must be allocated

separately (BUNDLE_TUPLE contains a pointer to the actual

tuple, not a character array).

BUNDLE_SPEC Structure containing enough information for the bundle agent

to generate a bundle header.

7/30/2019 Bundle API 0.2

9/28

7 File Descriptions

7

BUNDLE_ITERATOR Token supplied to bundle_poll() calls so that the bundle

agent can return only newly arrived bundles to the application.

BUNDLE_WAITING Structure that applications use to identify bundles destined forthem. A BUNDLE_WAITING structure is passed to the

bundle_poll() call, and is an argument of theasynchronous callback routine for incoming bundles.Contains a BUNDLE_SPEC, a filename, and the filename

length. Note that the filename is NOT NULL terminated.

2.4 Functions

BUNDLE_AGENT open_agent(char* bundleAgentHost)

void close_agent(BUNDLE_AGENT bundleAgent)

int local_region(char *regionName, int maxLength); int local_tuple(char *appSpecificPart, BUNDLE_TUPLE *tuple)

int local_tuple_withname(char *region,char *hostSpecificPart,

char *appSpecificPart,

BUNDLE_TUPLE *tuple)

int remote_tuple(char *region, char *admin, BUNDLE_TUPLE *tuple)

int bundle_spec(BUNDLE_COS cos,BUNDLE_DELIVERY_OPTS dopts,

BUNDLE_TUPLE src,

BUNDLE_TUPLE dst,

BUNDLE_TUPLE replyTo,

int32_t expire, BUNDLE_SPEC *bundleSpec)

int send_bundle_mem(BUNDLE_AGENT, BUNDLE_SPEC, char*, int)

int send_bundle_file(BUNDLE_AGENT, BUNDLE_SPEC, char*)

int demux_register(BUNDLE_AGENT agent, BUNDLE_TUPLE destTuple,BUNDLE_REG_ACTION reg_action,

uint32_t *cookie)

int demux_register_exec(BUNDLE_AGENT agent, BUNDLE_TUPLEdestTuple, char *argv, int argv_len,

uint32_t *cookie)

int demux_register_cancel(BUNDLE_AGENT, uint32_t)

int bundle_poll(BUNDLE_AGENT agent, BUNDLE_TUPLE destTuple,BUNDLE_ITERATOR *iterator,

BUNDLE_WAITING *waiting)

void print_tuple(BUNDLE_TUPLE)

void print_bundle_spec(BUNDLE_SPEC);

7/30/2019 Bundle API 0.2

10/28

8 File Descriptions

8

2.4.1 Function Documentation

2.4.1.1 BUNDLE_AGENT open_agent(char* bundleAgentHost)

Open an RPC connection to a bundle agent.

ParametersbundleAgentHost Host on which the bundle agent is running. Because the bundle API

uses RPCs to communicate between the application and the bundle agent, thebundle agent need not be on the same host as the application.

2.4.1.2 void close_agent(BUNDLE_AGENT agent)

Close an RPC connection to a bundle agent.

Parameters

agent bundle agent returned by open_agent().

2.4.1.3 int local_region(char *region, int maxSize)

Return the name of one of a DTN region in which the bundle agent has an interface.

Parameters

region Storage into which the region name will be copied (up to maxSize bytes).

maxSize The size of the storage (allocated by the application) pointed to by region.

2.4.1.4 int local_tuple(char *appSpecificPart, BUNDLE_TUPLE *tuple)

Generate a DTN tuple, allowing the bundle agent to fill in the region and host specific parts.That is, the DTN tuple is composed of a region name and a region-specific entity name. Theentity name itself may have a host-specific part (e.g. a hostname) and some application-specific

part (to demultiplex the bundle to a specific application on that host). This function generates a

tuple with the region and host-specific parts of the bundle agent, and an application-specific part

supplied by the caller. This function is useful, for example, to generate the source tuple forbundles an application is sending.

Parameters

appSpecificPart The application-specific part of the tuple.

tuple Pointer to the data structure into which the generated tuple is placed. Note that

the storage for the tuple itself (the character array inside the BUNDLE_TUPLEstructure) is a separate operation.

2.4.1.5 int local_tuple_withname(char *region, char *hostSpecificPart,char *appSpecificPart, BUNDLE_TUPLE *tuple)

Generate a DTN tuple, with the application providing the region and host specific parts. Nochecking is done to ensure that the region and host specific parts are legitimate. That is, the

7/30/2019 Bundle API 0.2

11/28

9 File Descriptions

9

bundle agent does not ensure that the tuple generated is a legitimate local tuple for this bundle

agent.

Parameters

region The DTN region for the tuple.

hostSpecificPart The host specific part of the tuple (part of the entity identifier that isopaque outside the destination region).appSpecificPart The application-specific part of the tuple (part of the entity identifier

that is opaque outside the destination region).tuple Pointer to the data structure into which the generated tuple is placed. Note that

the storage for the tuple itself (the character array inside the BUNDLE_TUPLE

structure) is a separate operation.

2.4.1.6 int remote_tuple(char *region, char *admin, BUNDLE_TUPLE *tuple)

Generate a DTN tuple, with the application providing the region and host specific parts.

Parameters

region The DTN region for the tuple.admin The entity identifier (the part that is opaque outside the destination region).

tuple Pointer to the data structure into which the generated tuple is placed. Note that

the storage for the tuple itself (the character array inside the BUNDLE_TUPLE

structure) is a separate operation.

2.4.1.7 int bundle_spec(BUNDLE_COS cos,BUNDLE_DELIVERY_OPTS dopts, BUNDLE_TUPLE src,

BUNDLE_TUPLE dst, BUNDLE_TUPLE replyTo, int32_t expire,BUNDLE_SPEC *bundleSpec)

Build a bundle spec, a structure containing the information needed to generate a bundle header.

BUNDLE_SPECs are passed, along with content or references to content, to the routines thatactually send bundles.

Parameters

cos Defines the class of service the application is requesting for this bundle. Values

for the COS parameter (in order of increasing precedence) are:COS_BULK

COS_NORMAL

COS_EXPEDITEDCOS_RESERVED.......Reserved for future use; not to be used by

applications.

Bundles with higher priorities are transmitted before bundles of lower priority.

Note that the class of service and requirements for reliable (custodial) delivery are

distinct.

7/30/2019 Bundle API 0.2

12/28

10 File Descriptions

10

dopts Specifies the delivery options the application is requesting for this bundle. These

are flags that can be logically ORed together to request multiple services.

COS_NONE ............................. No delivery options: the bundle will

receive best effort service.

COS_CUSTODY ...................... Application requests that the bundle be

delivered custodially.COS_RET_RCPT.................... Application requests that a return receipt

be generated when the bundle is delivered

to the receiving application. The receivingapplications bundle agent generates the

return receipt, which is sent to the

bundles reply-to tuple.

COS_DELIV_REC_FORW .....Request that bundle agents that forward

the bundle send delivery receipts to thebundles reply-to tuple when they transmit

the bundle.

COS_DELIV_REC_CUST .....Request that bundle agents taking custodyof the bundle send delivery receipts to the

bundles reply-to tuple.

src The source DTN tuple.

dst The destination DTN tuple.replyTo The reply-to DTN tuple.expire The lifetime of the bundle, in seconds.

bundleSpec pointer to data structure into which the bundle spec is placed.

2.4.1.8 int send_bundle_mem(BUNDLE_AGENT agent,

BUNDLE_SPEC bundleSpec, char *data, int length)Send a portion of memory as the payload of a bundle.

Parameters


bundleSpec a bundle specification (bundleSpec) returned by a call to

bundleSpec().

data pointer to memory that will be sent.length number of bytes to send from memory.

2.4.1.9 int send_bundle_file(BUNDLE_AGENT agent,BUNDLE_SPEC bundleSpec, char *fileName)

Send a bundle from a file. Note thatfileName references a file on the bundle agents file system.

If the application and bundle agent are not on the same host, this may generate unintended

results.

7/30/2019 Bundle API 0.2

13/28


11

Parameters



bundleSpec().

filename name of the file to send (on the bundle agents file system).

2.4.1.10 int demux_register(BUNDLE_AGENT agent,BUNDLE_TUPLE destTuple, BUNDLE_REG_ACTION action,uint32_t *cookie)

Register with a bundle agent to receive bundles destined for the specified endpointID.

Parameters

agent bundle agent returned by open_agent().destTuple destination tuple (tuple for which the application is requesting bundles).action One of the following:

BUNDLE_REG_ABORT .......... Used for applications that will provide acallback function for bundle reception.

BUNDLE_REG_DEFER .......... Unused should not be supplied by

applications.

BUNDLE_REG_EXEC............. Not implemented yet / unused.

BUNDLE_REG_CANCEL........ Unused (see

demux_register_cancel() below).

cookie An opaque token returned by the bundle agent that the application can later use

to reference this registration (as a parameter to demux_register_cancel(),

e.g.)

2.4.1.11 int demux_register_exec(BUNDLE_AGENT agent,BUNDLE_TUPLE endpointID, char *argv, int argv_len,uint32_t *cookie)

NOT IMPLEMENTED YET.

Parameters


endpointID tuple for which the application wants to receive bundles.argv arguments to be passed to the application when it is re-instantiated.argv_len number of arguments to pass to the application when it is re-instantiated.

cookie An opaque token returned by the bundle agent that the application can later useto reference this registration (as a parameter to demux_register_cancel(),

e.g.)

2.4.1.12 int demux_register_cancel(BUNDLE_AGENT agent,uint32_t cookie)

Cancel a registration with the bundle agent. After cancellation no more bundles for the

registration will be delivered to the application.

7/30/2019 Bundle API 0.2

14/28


12

Parameters


cookie Token returned by one of the demux_register_XXX() functions.

2.4.1.13 int bundle_poll(BUNDLE_AGENT agent,BUNDLE_TUPLE destTuple, BUNDLE_ITERATOR *iterator,BUNDLE_WAITING *waiting)

Poll for incoming bundles. Bundles matching the destTuple argument are returned via the

waitingparameter.

Parameters


destTuple destination tuple.

iterator Token that the bundle agent uses to determine which bundles the application

has already seen. The value of the iterator variable should be set toBUNDLE_ITERATOR_NONE before the first call to bundle_poll() and

should not be modified by the application.waiting Structure that contains information about a new bundle (if any) for the

application.

Returns BUNDLE_SUCCESS if there is at least one bundle for the application, in

which case the bundles information is returned via the waitingparameter.

2.4.1.14 void print_tuple(BUNDLE_TUPLE tuple)

Prints a BUNDLE_TUPLE to stdout.

Parameters

tuple Tuple to print.

2.4.1.15 void print_bundle_spec(BUNDLE_SPEC bundleSpec)

Prints a BUNDLE_SPEC to stdout.

Parameters


bundleSpec().

7/30/2019 Bundle API 0.2

15/28

Chapter 3

3 Sending Bundles

3.1 Step 0: Variable declarations

BUNDLE_AGENT bundleAgent; Opaque token returned by open_agent() and

provided to subsequent bundle calls.

BUNDLE_SPEC bundleSpec; Holds class of service information

associated with a send bundle request.

BUNDLE_TUPLE sourceTuple;

BUNDLE_TUPLE destTuple; These hold the source and destination tuples

(region names and endpoint identifiers).

Note that we have to allocate the storage for the tuple ourselves. Thus a common initialization

for tuples is:

char buf[1024];

BUNDLE_TUPLE tuple = {0, buf, 0};

3.2 Step 1: Open bundle agent connection

The first thing to do is to open an RPC connection to a bundle agent.

bundleAgent = openAgent(bundleAgentHost);

3.3 Step 2: Generate the source and destination tuples

The next step is to generate the source and destination tuples. Two helper functions are available

to generate the source tuple, local_tuple() and local_tuple_withname():

local_tuple (adminAppPart, &sourceTuple)

This generates a DTN tuple specifying only the application specific part of the entity ID. Thebundle agent sets the region and host-specific parts of the entity ID.

local_tuple_withname(region, adminHostPart, adminAppPart, &

sourceTuple)

7/30/2019 Bundle API 0.2

16/28

14 Sending Bundles

14

This generates a DTN tuple with the given source region and a source administrative part that

has sourceAdmin as the machine-specific part (hostname) and localstuff as the applicationspecific part.

A single helper function generates destination tuples:

remote_tuple(region, admin, &destTuple)

3.4 Step 4: Generate a bundle spec

The functions that actually send bundles take as an argument a bundleSpec. A bundleSpec

contains all of the information required to construct a bundle header. This includes class of

service (CoS) information, the bundle lifetime, and the source, destination, and reply-to tuples.

bundle_spec(COS_NORMAL, COS_NONE, sourceTuple, destTuple,replyToTuple, expire, &bundleSpec)

The first COS parameter

The second COS parameter

The expire parameter sets the lifetime of the bundle, in seconds, from the current time.

3.5 Step 5: Call one of the send_bundle_XXX functions

Two functions are available to send bundles either from memory or from a file.

send_bundle_mem(bundleAgent, bundleSpec, bundle_data,

length)

send_bundle_mem() sends length bytes in memory pointed to by bundle_data as the bundle

payload.

send_bundle_file(bundleAgent, bundleSpec, fileName)

send_bundle_file() uses the bundleSpec to send the filefilename as a bundle.

3.6 Step 6: Close the RPC Connection to the bundle agent

close_agent(ba);

7/30/2019 Bundle API 0.2

17/28

15 Sending Bundles

15

3.7 Sample Code snd_bundle.c

/*




* copy or use the software.*

* Intel Open Source License

*

* Copyright (c) 1996-2002 Intel Corporation. All rights reserved.

*

* Redistribution and use in source and binary forms, with or without

* modification, are permitted provided that the following conditions are met:

*


* this list of conditions and the following disclaimer.

*

* Redistributions in binary form must reproduce the above copyright

* notice, this list of conditions and the following disclaimer in the

* documentation and/or other materials provided with the distribution.

*

* Neither the name of the Intel Corporation nor the names of its



*

* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''

* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,


* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE INTEL OR ITS CONTRIBUTORS

* BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;

* OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,

* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF

* THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*/

#include

#include

#include

#include

#include "bundle_api.h"

char bahost[MAXHOSTNAMELEN] = "localhost";

char bundle_data[2048] = "";

char fname[PATH_MAX] = "";

char localstuff[MAX_TUPLE] = "snd_bundle_local_stuff";

char destRegion[1024] = "destRegion";

char destAdmin[1024] = "destAdmin";

char sourceRegion[1024] = "";

char sourceAdmin[1024] = "";

uint32_t expire = 100; // default time to live (seconds)

uint32_t theSource = 0; // 1 = memory; 2 = file; 3 = bothuint32_t debug = 0; // higher values cause more info to print

char sendBuf[2048]; // buffer to send from memory

uint32_t timesToLoop = 1; //

void usage(char *str1, char *str2);

void readCommandLineArgs(int argc, char **argv);

/*

* note: have to be sort of careful: underlying XDR routines that

* deal with character arrays evidently like to scribble in this string's

7/30/2019 Bundle API 0.2

18/28

16 Sending Bundles

16

* space. Thus, using string literals can result in SEGV problems when

* routines like xdr_char attempts to write into the write-protected

* segment where string literals are stored... (ouch)

*/

int

main(int argc, char **argv)

{

static char namebuf[1024]; /* space for tuple */static char namebuf2[1024]; /* space for tuple */

BUNDLE_AGENT ba;

BUNDLE_SPEC bs;

BUNDLE_TUPLE tuple = { { 0, namebuf} , 0 };

BUNDLE_TUPLE dst = { { 0, namebuf2}, 0};

BUNDLE_WAITING bw;

BUNDLE_ITERATOR iterator = BUNDLE_ITERATOR_NONE ;

uint32_t reg_cookie = BUNDLE_REG_COOKIE_NONE;

//

// Read the command arguments

//

readCommandLineArgs(argc, argv);

//

// Sanity check parameters

//if ( theSource==0 ) {

usage("snd_bundle", "-s option is required.");

exit(-1);

}

if ( (theSource==2 || theSource==3) && (strlen(fname)==0) ) {

usage("snd_bundle", "");

fprintf(stderr, "theSource (%d) specifies sending from file\n", theSource);

fprintf(stderr, "but no file name given.\n");

exit(-1);

}

//

// Open connection to bundle agent.

//

if ( debug>0 ) {

printf("SND BUNDLE: ***opening bundle agent on host %s\n", bahost);}

if ((ba = open_agent(bahost)) == NULL) {

fprintf(stderr, "couldn't contact bundle agent on %s\n", bahost);

exit(1);

}

if ( debug>1 ) {

printf(" Bundle agent open.\n");

}

//

// Local tuple

//

if ( debug>0 ) {

printf("snd_bundle: building local tuple with localstuff: '%s'\n",

localstuff);

}

//

// If the user specified a source region and source admin part, use those,

// otherwise call local_tuple which will use one of our regions (the first

// it finds in the config file) and our hostname.

//

if ( strlen(sourceRegion)>0 && strlen(sourceAdmin)>0 ) {

if ( local_tuple_withname(sourceRegion, sourceAdmin, localstuff, &tuple)

7/30/2019 Bundle API 0.2

19/28

17 Sending Bundles

17

} else {

if (local_tuple(localstuff, &tuple) < 0) {

fprintf(stderr, "trouble building tuple\n");

exit(1);

}

}

if ( debug>0 ) {

print_tuple(tuple);

}

//

// Destination tuple

//

if ( debug>0 ) {

printf("snd_bundle: building destination tuple: (%s, %s)'\n",

destRegion, destAdmin);

}

if (remote_tuple(destRegion, destAdmin, &dst) < 0) {

fprintf(stderr, "trouble building destination tuple\n");

exit(1);

}

if ( debug>0 ) {

print_tuple(dst);

}

while ( timesToLoop-->0 ) {//

// Send a bundle from memory

//

if ( theSource==1 || theSource==3 ) {

if ( debug>0 ) {

printf("sending bundle from memory...\n");

}

if (bundle_spec(COS_NORMAL, COS_NONE, tuple, dst, tuple, expire, &bs) < 0) {

fprintf(stderr, "trouble building bundle_spec\n");

exit(1);

}

if (send_bundle_mem(ba, bs, bundle_data, strlen(bundle_data)) < 0) {

fprintf(stderr, "trouble sending bundle from memory\n");

exit(1);

}

}

//

// Send a bundle from a file

//

if ( theSource==2 || theSource==3 ) {

if ( debug>0 ) {

printf("sending bundle from file...\n");

}

if (bundle_spec(COS_NORMAL, COS_NONE, tuple, dst, tuple, expire, &bs) < 0) {

fprintf(stderr, "trouble building bundle_spec\n");

exit(1);

}

if (send_bundle_file(ba, bs, fname) < 0) {

fprintf(stderr, "trouble sending bundle from file '%s'\n", fname);

exit(1);

}

}

}

if ( debug>0 ) {

printf("\n***all done (success)\n");

}

close_agent(ba);

exit(0);

}

void

readCommandLineArgs(int argc, char **argv)

7/30/2019 Bundle API 0.2

20/28

18 Sending Bundles

18

{

int c;

while ((c=getopt(argc, argv, "b:l:R:A:r:a:s:m:f:n:whd:"))!=EOF) {

switch(c) {

case 'b': // bundle agent host

strcpy(bahost, optarg);

break;

case 'l':strcpy(localstuff, optarg);

break;

case 'R': // destination region

strcpy(destRegion, optarg);

break;

case 'A': // destination admin part

strcpy(destAdmin, optarg);

break;

case 'r': // source region

strcpy(sourceRegion, optarg);

break;

case 'a': // source admin

strcpy(sourceAdmin, optarg);

break;

case 's': // source: 1=memory, 2=file, 3=both

theSource = atoi(optarg);

break;case 'm': // string to send from memory

strcpy(bundle_data, optarg);

break;

case 'f': // file to send, only makes sense for source=2 or 3

strcpy(fname, optarg);

break;

case 'w':

writeResourceFile = 1;

break;

case 'h':


exit(0);

break;

case 'n':

timesToLoop = atoi(optarg);

break;

case 'd':debug = atoi(optarg);

break;

default:

fprintf(stderr, "snd_bundle: unknown option: '%c'\n", (char) c);


exit(-1);

}

}

}

void

usage(char *str1, char *str2)

{

fprintf(stderr, "usage: %s ", str1);

fprintf(stderr, " [-b bundleAgent] specify bundle agent to use.\n");

fprintf(stderr, " [-r sourceRegion] source region.\n");

fprintf(stderr, " [-a sourceAdmin] - source entity ID\n");fprintf(stderr, " [-l localStuff] - specify the application specific \n");

fprintf(stderr, " part of the sourceAdmin tuple.\n");

fprintf(stderr, " [-R destRegion] - destination region\n");

fprintf(stderr, " [-A destAdmin] - destination entity ID\n");

fprintf(stderr, " [-e expire] - set expiration (delta seconds).");

fprintf(stderr, " -s bundlePayloadSource 1: send from memory\n");

fprintf(stderr, " 2: send from file.\n");

fprintf(stderr, " 3: send from memory and file.\n");

fprintf(stderr, " [-m string] - string to send when sending\n");

fprintf(stderr, " from memory.\n");

fprintf(stderr, " [-f fileToSend] - file to send when sending files.\n");

7/30/2019 Bundle API 0.2

21/28

19 Sending Bundles

19

fprintf(stderr, " [-n timesToLoop] - number of (identical) bundles to send\n");

fprintf(stderr, " (2n bundles if bundlePayloadSource is 3).\n");

fprintf(stderr, " [-d debugValue]\n");

fprintf(stderr, " [-h] - print this message.\n");

fprintf(stderr, "\n");

fprintf(stderr, " %s\n", str2);

}

7/30/2019 Bundle API 0.2

22/28

Chapter 4

4 Receiving Bundles

4.1 Step 0: Variable and function declarations

BUNDLE_AGENT bundleAgent; Opaque token returned by open_agent() and

provided to subsequent bundle calls.

extern int (*bundle_arrived_ptr)(BUNDLE_WAITING *); This

pointer is defined in libdtn. Set this

pointer to the applications receive_bundle

function.

int receive_bundle(BUNDLW_WAITING *bw) Callback routing for

asynchronous bundle reception.

4.2 Step 1: Open a connection to the bundle agent

The first thing to do is to open an RPC connection to a bundle agent.

bundleAgent = openAgent(bundleAgentHost);

4.3 Step 2: Create the destination tuple

This is the tuple that identifies bundles the application wants to receive.local_tuple(demuxKey, &tuple)

4.4 Step 3: Register the destination tuple with the bundle agent.

Let the bundle agent know you want bundles matching this destination tuple.

demux_register(bundleAgent, destTuple, BUNDLE_REG_ABORT,

&cookie)

4.5 Step 4: Receive Bundles

Applications can either poll for bundles or receive them via a callback function.

7/30/2019 Bundle API 0.2

23/28

21 Receiving Bundles

21

4.5.1 Polling Method

Applications can poll for new bundles with the bunle_poll() function

if ( bundle_poll(ba, tuple, &iterator, &bw )==BUNDLE_SUCCESS ) {

/* Process bundle */

}

4.5.2 Passive Bundle Reception (via callback function)

Applications that want to receive asynchronous notification of bundle arrivals need to set afunction pointer and then start the application RPC server:

bundle_arrived_ptr = Callback_Routine_to_Receive_Bundles;

svc_run();

After calling svc_run(),bundle agent RPC calls to the applications RPC server will cause

BUNDLE_WAITING structures to be passed to the callback function. svc_run() doesnt

return.

4.6 Sample Code rcv_bundle.c

/****************************************************************************

*





*

* Copyright (c) 2002, The MITRE Corporation

* All rights reserved.

*

* Redistribution and use in source and binary forms, with or without* modification, are permitted provided that the following conditions are

* met:

*


* this list of conditions and the following disclaimer. Redistributions

* in binary form must reproduce the above copyright notice, this list of

* conditions and the following disclaimer in the documentation and/or

* other materials provided with the distribution.

*

* Neither the name of The MITRE Corporation nor the names of its



*

* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS

* IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,


* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,

* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,

* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*

****************************************************************************/

#ifdef HAVE_CONFIG_H

# include

7/30/2019 Bundle API 0.2

24/28


22

#endif

#include

#include

#include

#include

#include

#include

#include #include

#include "bundle_api.h"

#define STATEFILENAME ".rcvBundle2State"

typedef struct rcvBundleState {

char bundleAgent[256];

char region[256];

char hostname[256];

char demuxKey[256];

uint32_t cookie;

} RCV_BUNDLE_STATE;

/** Default state:

* Bundle agent is running on this machine.

* Receive bundles destined for the 'loopback' region.

* My name in the 'loopback' region is localhost.

* Receive bundles whose application-demux part is 'demux'

*/

RCV_BUNDLE_STATE defaultState = {

"localhost", // bundleAgent

"loopback", // local region (receiving)

"localhost", // local host-specific piece of admin part

"demux", // local application-specific piece of admin part

0

};

RCV_BUNDLE_STATE myState;

BUNDLE_AGENT ba;int pollForBundles = 0;

pthread_t runThread;

void parseOptions(int argc, char **argv);

int receive_bundle(BUNDLE_WAITING *arrive_info);

extern int (*bundle_arrived_ptr)(BUNDLE_WAITING *);

static void SIGINTHandler(int signal);

void

parseOptions(int argc, char **argv)

{

int c;

while ((c=getopt(argc, argv, "a:r:l:d:wp"))!=EOF ) {

switch (c) {

case 'a':

strcpy(myState.bundleAgent, optarg);break;

case 'r':

strcpy(myState.region, optarg);

break;

case 'l':

strcpy(myState.hostname, optarg);

break;

case 'd':

strcpy(myState.demuxKey, optarg);

break;

case 'p':

7/30/2019 Bundle API 0.2

25/28


23

pollForBundles = 1;

default:

printf("unknown argument '%c'\n", c);

exit(EXIT_FAILURE);

}

}

}

/** This gets called when bundles arrive.

*

*/

int

receive_bundle(BUNDLE_WAITING *arrive_info)

{

static int count = 0;

struct stat statBuf;

char bundleFileName[1024];

memcpy(bundleFileName,

arrive_info->filename.filename_val,

arrive_info->filename.filename_len);

bundleFileName[arrive_info->filename.filename_len] = '\0';

if ( stat(bundleFileName, &statBuf)

7/30/2019 Bundle API 0.2

26/28


24

"couldn't contact bundle agent on %s\n", myState.bundleAgent);

exit(EXIT_FAILURE);

} else {

printf("bundle agent opened.\n");

}

/*

* API doesn't do mem alloc for us; we must do it

*/printf("creating local tuple...\n");

if (local_tuple_withname(myState.region,

myState.hostname,

myState.demuxKey,

&tuple) < 0) {

fprintf(stderr, "trouble building tuple\n");

exit(1);

}

print_tuple(tuple);

if ( ! pollForBundles ) {

/*

* Tell the api what our incoming bundle routine is.

*/

bundle_arrived_ptr = receive_bundle;

}

/*

* Register the tuple for which we want to receive bundles.

*/

printf("registering tuple...");

if (demux_register(ba, tuple, BUNDLE_REG_ABORT, &myState.cookie) != 0) {

fprintf(stderr, "trouble registering tuple\n");

exit(1);

}

printf("ok, cookie was 0x%x\n", myState.cookie);

if ( pollForBundles ) {

/*

* Already had to do signal handing (see below).

* There's going to be no way out of this polling loop

* short of CTRL-C.

*/

while ( 1 ) {printf("Sleeping for a bit...\n");

sleep(5);

printf("polling for tuple:\n");

print_tuple(tuple);

if ( bundle_poll(ba, tuple, &iterator, &bw)==BUNDLE_SUCCESS ) {

memcpy(bundleFileName,

bw.filename.filename_val,

bw.filename.filename_len);

bundleFileName[bw.filename.filename_len] = '\0';

printf("yup, got a bundle at %s\n", bundleFileName);

printf("with bundle spec:\n");

print_bundle_spec(bw.bs);

}

}

}

/*

* Call the RPC svc_run() function to process incoming bundles.

* The receive_bundle() function will be called when new bundles arrive.

*

* svc_run() doesn't return, and this is the main application

* thread, so CTRL-C is the only way out...

*/

printf("About to call svc_run()\n");

svc_run();

perror("svc_run() returned");

7/30/2019 Bundle API 0.2

27/28


25

exit(EXIT_FAILURE);

}

/*

* Signal processor cancel registration.

*/

static void

SIGINTHandler(int signal)

{ fprintf(stderr, "In SIGINTHandler(%d)\n", signal);

if ( demux_register_cancel(ba, myState.cookie)!=0 ) {

fprintf(stderr, "Problem deregistering cookie %d\n", myState.cookie);

exit(EXIT_FAILURE);

}

exit(EXIT_SUCCESS);

}

7/30/2019 Bundle API 0.2

28/28

5 References

[1] V. Cerf, et al, "Delay Tolerant Networking Architecture," work in progress, draft-irtf-

dtnrg-arch-doc-02.txt, March 2003.

[2] F. Warthman, "Delay-Tolerant Networks (DTNs): A Tutorial", Wartham Associates,Available from http://www.dtnrg.org

[3] S. Burleigh, et. al., " Bundle Protocol Specification," work in progress, draft-irtf-dtnrg-

bundle-spec-00.txt, March 2003.

Bundle API 0.2

Documents

Transcript of Bundle API 0.2