dtn::BundleProtocol Class Reference

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

#include <BundleProtocol.h>

List of all members.

Classes

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

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, REASON_SECURITY_FAILED = 0x09
}
 Bundle Status Report "Reason Code" flags. More...
enum  bundle_block_type_t {
  PRIMARY_BLOCK = 0x000, PAYLOAD_BLOCK = 0x001, BUNDLE_AUTHENTICATION_BLOCK = 0x002, PAYLOAD_SECURITY_BLOCK = 0x003,
  CONFIDENTIALITY_BLOCK = 0x004, PREVIOUS_HOP_BLOCK = 0x005, METADATA_BLOCK = 0x008, SESSION_BLOCK = 0x009,
  SEQUENCE_ID_BLOCK = 0x010, OBSOLETES_ID_BLOCK = 0x011, API_EXTENSION_BLOCK = 0x100, UNKNOWN_BLOCK = 0x101
}
 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, BLOCK_FLAG_EID_REFS = 1 << 6
}
 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 = 1 << 14, STATUS_CUSTODY_ACCEPTED = 1 << 15, STATUS_FORWARDED = 1 << 16, STATUS_DELIVERED = 1 << 17,
  STATUS_DELETED = 1 << 18, STATUS_ACKED_BY_APP = 1 << 19, STATUS_UNUSED2 = 1 << 20
}
 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 void reload_post_process (Bundle *bundle)
 Give the processors a chance to chew on the bundle after reloading from disk.
static BlockInfoVecprepare_blocks (Bundle *bundle, const LinkRef &link)
 Generate a BlockInfoVec for the outgoing link and put it into xmit_blocks_.
static size_t generate_blocks (Bundle *bundle, BlockInfoVec *blocks, const LinkRef &link)
 Generate contents for the given BlockInfoVec on the given Link.
static void delete_blocks (Bundle *bundle, const LinkRef &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 int set_timestamp (u_char *bp, size_t len, const BundleTimestamp &tv)
 Store a DTN timestamp into a 64-bit value suitable for transmission over the network.
static int get_timestamp (BundleTimestamp *tv, const u_char *bp, size_t len)
 Retrieve a DTN timestamp from a 64-bit value that was transmitted over the network.
static size_t ts_encoding_len (const BundleTimestamp &tv)
 Return the length required to encode the timestamp as two SDNVs.
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

struct
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 = 0x06
 The current version of the bundling protocol.
static const unsigned PREAMBLE_FIXED_LENGTH = 1

Static Private Attributes

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


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 40 of file BundleProtocol.h.


Member Enumeration Documentation

Administrative Record Flags.

Enumerator:
ADMIN_IS_FRAGMENT 

Definition at line 227 of file BundleProtocol.h.

Administrative Record Type Codes.

Enumerator:
ADMIN_STATUS_REPORT 
ADMIN_CUSTODY_SIGNAL 
ADMIN_ANNOUNCE 

Definition at line 218 of file BundleProtocol.h.

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 
BLOCK_FLAG_EID_REFS 

Definition at line 195 of file BundleProtocol.h.

Valid type codes for bundle blocks.

(See http://www.dtnrg.org/wiki/AssignedNamesAndNumbers)

Enumerator:
PRIMARY_BLOCK  INTERNAL ONLY -- NOT IN SPEC.
PAYLOAD_BLOCK 
BUNDLE_AUTHENTICATION_BLOCK 
PAYLOAD_SECURITY_BLOCK 
CONFIDENTIALITY_BLOCK 
PREVIOUS_HOP_BLOCK 
METADATA_BLOCK  NOT IN SPEC YET.
SESSION_BLOCK  NOT IN SPEC YET.
SEQUENCE_ID_BLOCK  NOT IN SPEC YET.
OBSOLETES_ID_BLOCK  NOT IN SPEC YET.
API_EXTENSION_BLOCK  INTERNAL ONLY -- NOT IN SPEC.
UNKNOWN_BLOCK  INTERNAL ONLY -- NOT IN SPEC.

Definition at line 176 of file BundleProtocol.h.

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 247 of file BundleProtocol.h.

Bundle Status Report Status Flags.

Enumerator:
STATUS_RECEIVED 
STATUS_CUSTODY_ACCEPTED 
STATUS_FORWARDED 
STATUS_DELIVERED 
STATUS_DELETED 
STATUS_ACKED_BY_APP 
STATUS_UNUSED2 

Definition at line 234 of file BundleProtocol.h.

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 
REASON_SECURITY_FAILED 

Definition at line 123 of file BundleProtocol.h.


Member Function Documentation

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 374 of file BundleProtocol.cc.

References dtn::BlockInfoVec::append_block(), ASSERT, BLOCK_FLAG_LAST_BLOCK, dtn::BlockProcessor::block_type(), dtn::BlockInfo::complete(), dtn::BlockProcessor::consume(), dtn::BlockInfo::contents(), find_processor(), dtn::BlockInfo::flags(), info, dtn::LOG, log_err_p, dtn::Bundle::mutable_recv_blocks(), dtn::BlockInfo::owner(), PRIMARY_BLOCK, and dtn::BlockInfo::type().

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

void dtn::BundleProtocol::delete_blocks ( Bundle bundle,
const LinkRef link 
) [static]

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

Find the appropriate BlockProcessor for the given block type code.

Definition at line 62 of file BundleProtocol.cc.

References processors_.

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

size_t dtn::BundleProtocol::generate_blocks ( Bundle bundle,
BlockInfoVec blocks,
const LinkRef 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 191 of file BundleProtocol.cc.

References ASSERT, BLOCK_FLAG_LAST_BLOCK, find_processor(), dtn::PrimaryBlockProcessor::generate_primary(), dtn::LOG, and PRIMARY_BLOCK.

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

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 612 of file BundleProtocol.cc.

References ADMIN_ANNOUNCE, ADMIN_CUSTODY_SIGNAL, ADMIN_STATUS_REPORT, buf, CASE, dtn::Bundle::is_admin(), dtn::Bundle::payload(), and dtn::BundlePayload::read_data().

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

int dtn::BundleProtocol::get_timestamp ( BundleTimestamp tv,
const u_char *  bp,
size_t  len 
) [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 584 of file BundleProtocol.cc.

References ASSERT, decode(), dtn::BundleTimestamp::seconds_, and dtn::BundleTimestamp::seqno_.

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

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

Initialize the default set of block processors.

Definition at line 73 of file BundleProtocol.cc.

References OBSOLETES_ID_BLOCK, register_processor(), and SEQUENCE_ID_BLOCK.

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

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 279 of file BundleProtocol.cc.

References PAYLOAD_BLOCK.

Referenced by dtn::ConnectionConvergenceLayer::close_contact(), and dtn::FragmentManager::try_to_reactively_fragment().

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

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 299 of file BundleProtocol.cc.

References ASSERT, BLOCK_FLAG_LAST_BLOCK, and dtn::LOG.

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

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 53 of file BundleProtocol.cc.

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

Referenced by init_default_processors().

void dtn::BundleProtocol::reload_post_process ( Bundle bundle  )  [static]

Give the processors a chance to chew on the bundle after reloading from disk.

Definition at line 89 of file BundleProtocol.cc.

References dtn::Bundle::mutable_recv_blocks().

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

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

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

Definition at line 569 of file BundleProtocol.cc.

References encode(), dtn::BundleTimestamp::seconds_, and dtn::BundleTimestamp::seqno_.

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

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

size_t dtn::BundleProtocol::ts_encoding_len ( const BundleTimestamp tv  )  [static]

Return the length required to encode the timestamp as two SDNVs.

Definition at line 605 of file BundleProtocol.cc.

References encoding_len(), dtn::BundleTimestamp::seconds_, and dtn::BundleTimestamp::seqno_.

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

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 452 of file BundleProtocol.cc.

References dtn::Bundle::fragmented_incoming(), dtn::LOG, log_err_p, dtn::Bundle::mutable_recv_blocks(), PAYLOAD_BLOCK, PRIMARY_BLOCK, REASON_BLOCK_UNINTELLIGIBLE, and REASON_SECURITY_FAILED.

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


Member Data Documentation

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

The current version of the bundling protocol.

Definition at line 168 of file BundleProtocol.h.

Referenced by dtn::PrimaryBlockProcessor::consume(), dtn::PrimaryBlockProcessor::generate_primary(), and dtn::PrimaryBlockProcessor::get_primary_len().

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

const unsigned dtn::BundleProtocol::PREAMBLE_FIXED_LENGTH = 1 [static]

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

Definition at line 271 of file BundleProtocol.h.

Referenced by find_processor(), and register_processor().


The documentation for this class was generated from the following files:

Generated on Fri Jan 30 09:43:13 2009 for DTN Reference Implementation by  doxygen 1.5.8