dtn::BundleProtocol Class Reference

#include <BundleProtocol.h>

List of all members.


Detailed Description

Centralized class used to convert a Bundle to / from the bundle protocol specification for the "on-the-wire" representation.

The actual implementation of this is mostly encapsulated in the BlockProcessor class hierarchy.

Definition at line 39 of file BundleProtocol.h.

Public Types

enum  status_report_reason_t {
  REASON_NO_ADDTL_INFO = 0x00, REASON_LIFETIME_EXPIRED = 0x01, REASON_FORWARDED_UNIDIR_LINK = 0x02, REASON_TRANSMISSION_CANCELLED = 0x03,
  REASON_DEPLETED_STORAGE = 0x04, REASON_ENDPOINT_ID_UNINTELLIGIBLE = 0x05, REASON_NO_ROUTE_TO_DEST = 0x06, REASON_NO_TIMELY_CONTACT = 0x07,
  REASON_BLOCK_UNINTELLIGIBLE = 0x08
}
 Bundle Status Report "Reason Code" flags. More...
enum  bundle_block_type_t { PRIMARY_BLOCK = 0x000, PAYLOAD_BLOCK = 0x001, PREVIOUS_HOP_BLOCK = 0x005, API_EXTENSION_BLOCK = 0x100 }
 Valid type codes for bundle blocks. More...
enum  block_flag_t {
  BLOCK_FLAG_REPLICATE = 1 << 0, BLOCK_FLAG_REPORT_ONERROR = 1 << 1, BLOCK_FLAG_DISCARD_BUNDLE_ONERROR = 1 << 2, BLOCK_FLAG_LAST_BLOCK = 1 << 3,
  BLOCK_FLAG_DISCARD_BLOCK_ONERROR = 1 << 4, BLOCK_FLAG_FORWARDED_UNPROCESSED = 1 << 5
}
 Values for block processing flags that appear in all blocks except the primary block. More...
enum  admin_record_type_t { ADMIN_STATUS_REPORT = 0x01, ADMIN_CUSTODY_SIGNAL = 0x02, ADMIN_ANNOUNCE = 0x05 }
 Administrative Record Type Codes. More...
enum  admin_record_flags_t { ADMIN_IS_FRAGMENT = 0x01 }
 Administrative Record Flags. More...
enum  status_report_flag_t {
  STATUS_RECEIVED = 0x01, STATUS_CUSTODY_ACCEPTED = 0x02, STATUS_FORWARDED = 0x04, STATUS_DELIVERED = 0x08,
  STATUS_DELETED = 0x10, STATUS_ACKED_BY_APP = 0x20, STATUS_UNUSED = 0x40, STATUS_UNUSED2 = 0x80
}
 Bundle Status Report Status Flags. More...
enum  custody_signal_reason_t {
  CUSTODY_NO_ADDTL_INFO = 0x00, CUSTODY_REDUNDANT_RECEPTION = 0x03, CUSTODY_DEPLETED_STORAGE = 0x04, CUSTODY_ENDPOINT_ID_UNINTELLIGIBLE = 0x05,
  CUSTODY_NO_ROUTE_TO_DEST = 0x06, CUSTODY_NO_TIMELY_CONTACT = 0x07, CUSTODY_BLOCK_UNINTELLIGIBLE = 0x08
}
 Custody Signal Reason Codes. More...

Static Public Member Functions

static void register_processor (BlockProcessor *bp)
 Register a new BlockProcessor handler to handle the given block type code when received off the wire.
static BlockProcessorfind_processor (u_int8_t type)
 Find the appropriate BlockProcessor for the given block type code.
static void init_default_processors ()
 Initialize the default set of block processors.
static BlockInfoVecprepare_blocks (Bundle *bundle, Link *link)
 Generate a BlockInfoVec for the outgoing link and put it into xmit_blocks_.
static size_t generate_blocks (Bundle *bundle, BlockInfoVec *blocks, Link *link)
 Generate contents for the given BlockInfoVec on the given Link.
static size_t total_length (const BlockInfoVec *blocks)
 Return the total length of the formatted bundle block data.
static size_t payload_offset (const BlockInfoVec *blocks)
 Temporary helper function to find the offset of the first byte of the payload in a block list.
static size_t produce (const Bundle *bundle, const BlockInfoVec *blocks, u_char *data, size_t offset, size_t len, bool *last)
 Copies out a chunk of formatted bundle data at a specified offset from the provided BlockList.
static int consume (Bundle *bundle, u_char *data, size_t len, bool *last)
 Parse the supplied chunk of arriving data and append it to the rcvd_blocks_ list in the given bundle, finding the appropriate BlockProcessor element and calling its receive() handler.
static bool validate (Bundle *bundle, status_report_reason_t *reception_reason, status_report_reason_t *deletion_reason)
 Loop through the bundle's received block list to validate each entry.
static void set_timestamp (u_char *bp, const BundleTimestamp *tv)
 Store a DTN timestamp into a 64-bit value suitable for transmission over the network.
static void set_timestamp (u_int64_t *bp, const BundleTimestamp *tv)
 Store a DTN timestamp into a 64-bit value suitable for transmission over the network.
static void get_timestamp (BundleTimestamp *tv, const u_char *bp)
 Retrieve a DTN timestamp from a 64-bit value that was transmitted over the network.
static void get_timestamp (BundleTimestamp *tv, const u_int64_t *bp)
 Retrieve a DTN timestamp from a 64-bit value that was transmitted over the network.
static bool get_admin_type (const Bundle *bundle, admin_record_type_t *type)
 Assuming the given bundle is an administrative bundle, extract the admin bundle type code from the bundle's payload.

Public Attributes

dtn::BundleProtocol::BlockPreamble packed
 The basic block preamble that's common to all blocks (including the payload block but not the primary block).

Static Public Attributes

static const int CURRENT_VERSION = 0x04
 The current version of the bundling protocol.

Static Private Attributes

static BlockProcessorprocessors_ [256]
 Array of registered BlockProcessor handlers -- fixed size since there can be at most one handler per protocol type.

Classes

struct  BlockPreamble
 The basic block preamble that's common to all blocks (including the payload block but not the primary block). More...


Member Enumeration Documentation

enum dtn::BundleProtocol::status_report_reason_t

Bundle Status Report "Reason Code" flags.

Enumerator:
REASON_NO_ADDTL_INFO 
REASON_LIFETIME_EXPIRED 
REASON_FORWARDED_UNIDIR_LINK 
REASON_TRANSMISSION_CANCELLED 
REASON_DEPLETED_STORAGE 
REASON_ENDPOINT_ID_UNINTELLIGIBLE 
REASON_NO_ROUTE_TO_DEST 
REASON_NO_TIMELY_CONTACT 
REASON_BLOCK_UNINTELLIGIBLE 

Definition at line 114 of file BundleProtocol.h.

enum dtn::BundleProtocol::bundle_block_type_t

Valid type codes for bundle blocks.

Enumerator:
PRIMARY_BLOCK  INTERNAL USE ONLY -- NOT IN SPEC.
PAYLOAD_BLOCK 
PREVIOUS_HOP_BLOCK 
API_EXTENSION_BLOCK  INTERNAL USE ONLY -- NOT IN SPEC.

Definition at line 177 of file BundleProtocol.h.

enum dtn::BundleProtocol::block_flag_t

Values for block processing flags that appear in all blocks except the primary block.

Enumerator:
BLOCK_FLAG_REPLICATE 
BLOCK_FLAG_REPORT_ONERROR 
BLOCK_FLAG_DISCARD_BUNDLE_ONERROR 
BLOCK_FLAG_LAST_BLOCK 
BLOCK_FLAG_DISCARD_BLOCK_ONERROR 
BLOCK_FLAG_FORWARDED_UNPROCESSED 

Definition at line 188 of file BundleProtocol.h.

enum dtn::BundleProtocol::admin_record_type_t

Administrative Record Type Codes.

Enumerator:
ADMIN_STATUS_REPORT 
ADMIN_CUSTODY_SIGNAL 
ADMIN_ANNOUNCE 

Definition at line 210 of file BundleProtocol.h.

enum dtn::BundleProtocol::admin_record_flags_t

Administrative Record Flags.

Enumerator:
ADMIN_IS_FRAGMENT 

Definition at line 219 of file BundleProtocol.h.

enum dtn::BundleProtocol::status_report_flag_t

Bundle Status Report Status Flags.

Enumerator:
STATUS_RECEIVED 
STATUS_CUSTODY_ACCEPTED 
STATUS_FORWARDED 
STATUS_DELIVERED 
STATUS_DELETED 
STATUS_ACKED_BY_APP 
STATUS_UNUSED 
STATUS_UNUSED2 

Definition at line 226 of file BundleProtocol.h.

enum dtn::BundleProtocol::custody_signal_reason_t

Custody Signal Reason Codes.

Enumerator:
CUSTODY_NO_ADDTL_INFO 
CUSTODY_REDUNDANT_RECEPTION 
CUSTODY_DEPLETED_STORAGE 
CUSTODY_ENDPOINT_ID_UNINTELLIGIBLE 
CUSTODY_NO_ROUTE_TO_DEST 
CUSTODY_NO_TIMELY_CONTACT 
CUSTODY_BLOCK_UNINTELLIGIBLE 

Definition at line 240 of file BundleProtocol.h.


Member Function Documentation

void dtn::BundleProtocol::register_processor ( BlockProcessor bp  )  [static]

Register a new BlockProcessor handler to handle the given block type code when received off the wire.

Definition at line 43 of file BundleProtocol.cc.

References ASSERT, dtn::BlockProcessor::block_type(), and processors_.

Referenced by init_default_processors().

BlockProcessor * dtn::BundleProtocol::find_processor ( u_int8_t  type  )  [static]

Find the appropriate BlockProcessor for the given block type code.

Definition at line 52 of file BundleProtocol.cc.

References processors_.

Referenced by consume(), prepare_blocks(), and dtn::BlockInfo::serialize().

void dtn::BundleProtocol::init_default_processors (  )  [static]

Initialize the default set of block processors.

Definition at line 63 of file BundleProtocol.cc.

References register_processor().

Referenced by dtn::BundleDaemon::do_init().

BlockInfoVec * dtn::BundleProtocol::prepare_blocks ( Bundle bundle,
Link link 
) [static]

Generate a BlockInfoVec for the outgoing link and put it into xmit_blocks_.

Returns:
a pointer to the new block list

Definition at line 73 of file BundleProtocol.cc.

References dtn::Bundle::api_blocks_, ASSERT, dtn::LinkBlockSet::create_blocks(), find_processor(), dtn::BlockInfoVec::has_block(), dtn::BlockProcessor::prepare(), PRIMARY_BLOCK, dtn::Bundle::recv_blocks_, and dtn::Bundle::xmit_blocks_.

Referenced by dtn::BundleActions::send_bundle().

size_t dtn::BundleProtocol::generate_blocks ( Bundle bundle,
BlockInfoVec blocks,
Link link 
) [static]

Generate contents for the given BlockInfoVec on the given Link.

Returns:
the total length of the formatted blocks for this bundle.

Definition at line 125 of file BundleProtocol.cc.

References ASSERT, BLOCK_FLAG_LAST_BLOCK, dtn::LOG, log_debug_p, and PRIMARY_BLOCK.

Referenced by dtn::BundleActions::send_bundle().

size_t dtn::BundleProtocol::total_length ( const BlockInfoVec blocks  )  [static]

Return the total length of the formatted bundle block data.

Definition at line 173 of file BundleProtocol.cc.

Referenced by dtn::StreamConvergenceLayer::Connection::check_completed(), dtn::BundleDaemon::handle_bundle_transmitted(), dtn::StreamConvergenceLayer::Connection::handle_send_bundle(), dtn::UDPConvergenceLayer::Sender::send_bundle(), and dtn::NullConvergenceLayer::send_bundle().

size_t dtn::BundleProtocol::payload_offset ( const BlockInfoVec blocks  )  [static]

Temporary helper function to find the offset of the first byte of the payload in a block list.

Definition at line 188 of file BundleProtocol.cc.

References PAYLOAD_BLOCK.

Referenced by dtn::CLConnection::close_contact(), dtn::BundleDaemon::handle_bundle_received(), and dtn::BundleDaemon::handle_bundle_transmitted().

size_t dtn::BundleProtocol::produce ( const Bundle bundle,
const BlockInfoVec blocks,
u_char *  data,
size_t  offset,
size_t  len,
bool last 
) [static]

Copies out a chunk of formatted bundle data at a specified offset from the provided BlockList.

Returns:
the length of the chunk produced (up to the supplied length) and sets *last to true if the bundle is complete.

Definition at line 208 of file BundleProtocol.cc.

References ASSERT, BLOCK_FLAG_LAST_BLOCK, dtn::LOG, and log_debug_p.

Referenced by dtn::UDPConvergenceLayer::Sender::send_bundle(), and dtn::StreamConvergenceLayer::Connection::send_data_todo().

int dtn::BundleProtocol::consume ( Bundle bundle,
u_char *  data,
size_t  len,
bool last 
) [static]

Parse the supplied chunk of arriving data and append it to the rcvd_blocks_ list in the given bundle, finding the appropriate BlockProcessor element and calling its receive() handler.

When called repeatedly for arriving chunks of data, this properly fills in the entire bundle, including the in_blocks_ record of the arriving blocks and the payload (which is stored externally).

Returns:
the length of data consumed or -1 on protocol error, plus sets *last to true if the bundle is complete.

Definition at line 282 of file BundleProtocol.cc.

References ASSERT, BLOCK_FLAG_LAST_BLOCK, find_processor(), info, dtn::LOG, log_debug_p, log_err_p, PRIMARY_BLOCK, and dtn::Bundle::recv_blocks_.

Referenced by dtn::StreamConvergenceLayer::Connection::handle_data_todo(), and dtn::UDPConvergenceLayer::Receiver::process_data().

bool dtn::BundleProtocol::validate ( Bundle bundle,
status_report_reason_t reception_reason,
status_report_reason_t deletion_reason 
) [static]

Loop through the bundle's received block list to validate each entry.

Returns:
true if the bundle is valid, false if it should be deleted.

Definition at line 359 of file BundleProtocol.cc.

References dtn::LOG, log_err_p, REASON_BLOCK_UNINTELLIGIBLE, and dtn::Bundle::recv_blocks_.

Referenced by dtn::BundleDaemon::handle_bundle_received().

void dtn::BundleProtocol::set_timestamp ( u_char *  bp,
const BundleTimestamp tv 
) [static]

Store a DTN timestamp into a 64-bit value suitable for transmission over the network.

Definition at line 435 of file BundleProtocol.cc.

References dtn::BundleTimestamp::seconds_, and dtn::BundleTimestamp::seqno_.

Referenced by dtn::CustodySignal::create_custody_signal(), dtn::BundleStatusReport::create_status_report(), dtn::PrimaryBlockProcessor::generate(), and set_timestamp().

static void dtn::BundleProtocol::set_timestamp ( u_int64_t *  bp,
const BundleTimestamp tv 
) [inline, static]

Store a DTN timestamp into a 64-bit value suitable for transmission over the network.

The implementation doesn't require the 64-bit destination to be word-aligned so it is safe to cast here.

Definition at line 149 of file BundleProtocol.h.

References set_timestamp().

void dtn::BundleProtocol::get_timestamp ( BundleTimestamp tv,
const u_char *  bp 
) [static]

Retrieve a DTN timestamp from a 64-bit value that was transmitted over the network.

This does not require the timestamp to be word-aligned.

Definition at line 449 of file BundleProtocol.cc.

References dtn::BundleTimestamp::seconds_, and dtn::BundleTimestamp::seqno_.

Referenced by dtn::PrimaryBlockProcessor::consume(), get_timestamp(), dtn::CustodySignal::parse_custody_signal(), and dtn::BundleStatusReport::parse_status_report().

static void dtn::BundleProtocol::get_timestamp ( BundleTimestamp tv,
const u_int64_t *  bp 
) [inline, static]

Retrieve a DTN timestamp from a 64-bit value that was transmitted over the network.

This does not require the timestamp to be word-aligned.

Definition at line 165 of file BundleProtocol.h.

References get_timestamp().

bool dtn::BundleProtocol::get_admin_type ( const Bundle bundle,
admin_record_type_t type 
) [static]

Assuming the given bundle is an administrative bundle, extract the admin bundle type code from the bundle's payload.

Returns:
true if successful

Definition at line 463 of file BundleProtocol.cc.

References ADMIN_ANNOUNCE, ADMIN_CUSTODY_SIGNAL, ADMIN_STATUS_REPORT, CASE, dtn::Bundle::is_admin_, NOTREACHED, dtn::Bundle::payload_, and dtn::BundlePayload::read_data().

Referenced by dtn::TclRegistration::parse_bundle_data(), and dtn::BundleStatusReport::parse_status_report().


Member Data Documentation

const int dtn::BundleProtocol::CURRENT_VERSION = 0x04 [static]

The current version of the bundling protocol.

Definition at line 172 of file BundleProtocol.h.

Referenced by dtn::PrimaryBlockProcessor::consume(), and dtn::PrimaryBlockProcessor::generate().

struct dtn::BundleProtocol::BlockPreamble dtn::BundleProtocol::packed

The basic block preamble that's common to all blocks (including the payload block but not the primary block).

BlockProcessor * dtn::BundleProtocol::processors_ [static, private]

Array of registered BlockProcessor handlers -- fixed size since there can be at most one handler per protocol type.

Definition at line 264 of file BundleProtocol.h.

Referenced by find_processor(), and register_processor().


The documentation for this class was generated from the following files:
Generated on Thu Jun 7 12:54:32 2007 for DTN Reference Implementation by  doxygen 1.5.1