|
1 <html> |
|
2 <head> |
|
3 <title> DTN2 Manual: Architecture </title> |
|
4 <link rel="stylesheet" type="text/css" href="manual.css" /> |
|
5 </head> |
|
6 <body> |
|
7 <a name="arch"/> |
|
8 <h1>Architecture of DTN2 |
|
9 </h1> |
|
10 |
|
11 <h2>Implementation overview</h2> |
|
12 |
|
13 <p> |
|
14 The following text is intended to provide a sketch of how the whole thing fits together. It is a brief synopsis of DTN2s implementation, taken entirely from <a href="http://www.cs.berkeley.edu/~demmer/papers/dtn-irb-tr-04-020.pdf">this paper</a> by Michael Demmer and others. For more information about DTN2's architecture and role as a platform for experimentation, see <a |
|
15 href="http://www.cs.berkeley.edu/~demmer/papers/dtn-irb-tr-04-020.pdf">this paper</a>. |
|
16 |
|
17 <h3><The major components</h3> |
|
18 |
|
19 <p>The major message processing, management and application support modules of the DTN Bundle forwarding system are provided below. The bundle router module requires the most detailed information regarding the state of the system upon which to base routing decisions. Decisions made by the router are passed as a set of instructions (actions) to the forwarder which is responsible for executing the actions.</p> |
|
20 |
|
21 <p>This separation between policy and function allows for easy extension, modification, and replacement of the potentially complex router module.</p> |
|
22 |
|
23 <h3>Bundle Router and Bundle Forwarder</h3> |
|
24 |
|
25 <p>The router component implements all the route selection |
|
26 and scheduling policy decision making. It takes as input a large variety of events that could potentially affect routing decisions and issues encoded instructions that are passed to the bundle forwarder, which is in turn charged with the responsibility to execute them. The forwarder executes the router’s decisions by interacting with the Convergence Layers, Registrations, and the Persistent Store. The separation of router from forwarder represents an instance of separating policy from mechanism. Separating the calculation of instructions from their execution helps to isolate the routing code from changes in the other internal APIs. |
|
27 |
|
28 <h3>Convergence Layers</h3> |
|
29 <p>Convergence Layers are the adapters between the DTN bundling protocols and various underlying transports, similar to drivers within an operating system. At the most basic level, they perform basic data plane functions: a particular layer must be able to transmit and receive bundles over a single hop (in the overlay topology). In some cases they also process signaling information required by the bundle router (e.g. such as failed connections and restarts). Convergence Layers are discussed in more detail in the following section. |
|
30 |
|
31 <h3>Persistent Store</h3> |
|
32 <p>Persistent storage is used to hold the contents of bundles during the store-and-forward process. A common abstraction for persistent storage allows a particular system instance to select (at runtime) to use either a relational database model or a simple file model. |
|
33 |
|
34 <h3>Fragmentation Module</h3> |
|
35 <p>The fragmentation module is responsible for fragmenting and reassembling bundle fragments. This module is capable of sending a signal to the bundle router when all the fragments of a subject bundle have been received. |
|
36 |
|
37 <h3>Contact Manager</h3> |
|
38 <p>The Contact Manager is responsible for keeping track of which links are currently available, any historical information regarding their connectivity or performance, |
|
39 and any known future schedules of when connectivity may be available. The primary task of the contact manager is to transform the information learned about contacts from |
|
40 environment-specific mechanisms into abstract contact descriptions that can be used by the bundle router. |
|
41 |
|
42 <h3>Management Interface</h3> |
|
43 <p>The management interface is used to signal the bundle router about any special policy constraints or preferences that may affect its data routing decisions. It is implemented as a generic interprocess communication capability so that multiple applications or processes may be supported. |
|
44 |
|
45 <h3>Console / Config</h3> |
|
46 <p>The console/configuration module provides a command line interface and an event loop for testing and debugging of the implementation, as well as a structured method |
|
47 to set initial configuration options. An embedded Tcl interpreter is used to parse and execute user commands and settings. |
|
48 |
|
49 <h3>Application IPC / Registration Module</h3> |
|
50 <p>DTN applications are written to use a thin library that communicates with the router via an inter-process communication channel. Most of this interaction relates to |
|
51 sending and receiving application messages and manipulating message demultiplexing bindings. |
|
52 |
|
53 </i> |
|
54 |
|
55 <p> |
|
56 <a name="DTN2 api"/> |
|
57 <h2>DTN2 API</h2> |
|
58 <a name="API functions"/> |
|
59 <h3>API functions</h3> |
|
60 <p> |
|
61 <table> |
|
62 <tr> |
|
63 <th>Interface |
|
64 <th>Function |
|
65 <th>Returns |
|
66 <th>Comments |
|
67 |
|
68 <tr> |
|
69 <td>Open a new connection to the router. |
|
70 <td><tt>extern int dtn_open(dtn_handle_t* handle)</tt> |
|
71 <td> DTN_SUCCESS | dtn_errno error code. |
|
72 <td> On success, initializes the handle parameter as a new handle |
|
73 to the daemon and returns DTN_SUCCESS. On failure, sets handle to |
|
74 NULL and returns a dtn_errno error code. |
|
75 |
|
76 <tr> |
|
77 <td>Close an open dtn handle. |
|
78 <td><tt>extern int dtn_close(dtn_handle_t handle);</tt> |
|
79 <td>DTN_SUCCESS |
|
80 <td>Returns DTN_SUCCESS on success. |
|
81 |
|
82 <tr> |
|
83 <td>Get the error associated with the given handle. |
|
84 <td><tt>extern int dtn_errno(dtn_handle_t handle);</tt> |
|
85 <td>TBC |
|
86 <td>None |
|
87 |
|
88 <tr> |
|
89 <td>Set the error associated with the given handle |
|
90 <td><tt>extern void dtn_set_errno(dtn_handle_t handle, int err);</tt> |
|
91 <td>TBC |
|
92 <td>None |
|
93 |
|
94 <tr> |
|
95 <td>Build a local endpoint id |
|
96 <td><tt>extern int dtn_build_local_eid(dtn_handle_t handle, |
|
97 dtn_endpoint_id_t* local_eid, |
|
98 const char* service_tag);</tt> |
|
99 <td>TBC |
|
100 <td>Build an appropriate local endpoint id by appending the specified |
|
101 service tag to the daemon's preferred administrative endpoint id. |
|
102 |
|
103 <tr> |
|
104 <td>Create a dtn registration. |
|
105 <td><tt>extern int dtn_register(dtn_handle_t handle, |
|
106 dtn_reg_info_t* reginfo, |
|
107 dtn_reg_id_t* newregid);</tt> |
|
108 <td>TBC |
|
109 <td>If the init_passive flag in the reginfo struct is true, |
|
110 the registration is initially in passive state, requiring |
|
111 a call to dtn_bind to activate it. Otherwise, the call to |
|
112 dtn_bind is unnecessary as the registration will be created |
|
113 in the active state and bound to the handle. |
|
114 |
|
115 <tr> |
|
116 <td>Remove a dtn registration. |
|
117 <td><tt>extern int dtn_unregister(dtn_handle_t handle, |
|
118 dtn_reg_id_t regid);</tt> |
|
119 <td>TBC |
|
120 <td>If the registration is in the passive state (i.e. not bound to any |
|
121 handle), it is immediately removed from the system. If it is in |
|
122 active state and bound to the given handle, the removal is deferred |
|
123 until the handle unbinds the registration or closes. This allows |
|
124 applications to pre-emptively call unregister so they don't leak |
|
125 registrations. |
|
126 |
|
127 <tr> |
|
128 <td>Check for an existing registration. |
|
129 <td><tt>extern int dtn_find_registration(dtn_handle_t handle, |
|
130 dtn_endpoint_id_t* eid, |
|
131 dtn_reg_id_t* newregid);</tt> |
|
132 <td>DTN_SUCCESS | ENOENT |
|
133 <td>Check for an existing registration on the given endpoint id. |
|
134 Return DTN_SUCCESS and fill in the registration id if it |
|
135 exists, or return ENOENT if it doesn't. |
|
136 |
|
137 <tr> |
|
138 <td>Modify an existing registration. |
|
139 <td><tt>extern int dtn_change_registration(dtn_handle_t handle, |
|
140 dtn_reg_id_t regid, |
|
141 dtn_reg_info_t *reginfo);</tt> |
|
142 <td>TBC |
|
143 <td>None |
|
144 |
|
145 <tr> |
|
146 <td>Associate a registration with the current ipc channel. |
|
147 <td><tt>extern int dtn_bind(dtn_handle_t handle, dtn_reg_id_t regid);</tt> |
|
148 <td>TBC |
|
149 <td>Associate a registration with the current ipc channel. |
|
150 This serves to put the registration in "active" mode. |
|
151 |
|
152 <tr> |
|
153 <td>Explicitly remove an association from the current ipc handle. |
|
154 <td><tt>extern int dtn_unbind(dtn_handle_t handle, dtn_reg_id_t regid);</tt> |
|
155 <td>TBC |
|
156 <td>Note that this is also implicitly done when the handle is closed. |
|
157 This serves to put the registration back in "passive" mode. |
|
158 |
|
159 |
|
160 <tr> |
|
161 <td>Send a bundle. |
|
162 <td><tt>extern int dtn_send(dtn_handle_t handle, |
|
163 dtn_reg_id_t regid, |
|
164 dtn_bundle_spec_t* spec, |
|
165 dtn_bundle_payload_t* payload, |
|
166 dtn_bundle_id_t* id);</tt> |
|
167 <td>TBC |
|
168 <td>Send a bundle either from memory or from a file. |
|
169 |
|
170 <tr> |
|
171 <td>Cancel a bundle transmission. |
|
172 <td><tt>extern int dtn_cancel(dtn_handle_t handle, |
|
173 dtn_bundle_id_t* id);</tt> |
|
174 <td>TBC |
|
175 <td>None |
|
176 |
|
177 <tr> |
|
178 <td>Blocking receive for a bundle. |
|
179 <td><tt>extern int dtn_recv(dtn_handle_t handle, |
|
180 dtn_bundle_spec_t* spec, |
|
181 dtn_bundle_payload_location_t location, |
|
182 dtn_bundle_payload_t* payload, |
|
183 dtn_timeval_t timeout);</tt> |
|
184 <td>TBC |
|
185 <td>Fill in the spec and payload structures with the bundle data. |
|
186 The location parameter indicates the manner by which the caller |
|
187 wants to receive payload data (i.e. either in memory or in a file). |
|
188 The timeout parameter specifies an interval in milliseconds to block |
|
189 on the server-side (-1 means infinite wait). |
|
190 <p>Note that it is advisable to call dtn_free_payload on the returned structure, |
|
191 otherwise the XDR routines will memory leak. |
|
192 |
|
193 <tr> |
|
194 <td>Blocking query for new subscribers on a session. |
|
195 <td><tt>extern int dtn_session_update(dtn_handle_t handle, |
|
196 unsigned int* status, |
|
197 dtn_endpoint_id_t* session, |
|
198 dtn_timeval_t timeout);</tt> |
|
199 <td>Indication that a subscriber was added or removed. |
|
200 <td>One or more registrations must have been bound to the handle |
|
201 with the SESSION_CUSTODY flag set. Returns an indication |
|
202 that the subscription state in the given session has changed |
|
203 |
|
204 |
|
205 <tr> |
|
206 <td>Return a file descriptor for the given handle. |
|
207 <td><tt>extern int dtn_poll_fd(dtn_handle_t handle);</tt> |
|
208 <td>File descriptor. |
|
209 <td>Return a file descriptor for the given handle. suitable for calling |
|
210 poll() or select() in conjunction with a call to dtn_begin_poll(). |
|
211 |
|
212 <tr> |
|
213 |
|
214 <td>Begin a polling period for incoming bundles. |
|
215 <td><tt>extern int dtn_begin_poll(dtn_handle_t handle, dtn_timeval_t timeout);</tt> |
|
216 <td>File descriptor |
|
217 <td>Returns a file descriptor suitable for calling poll() or select() on |
|
218 (similar to dtn_poll_fd). Note that dtn_bind() must have been |
|
219 previously called at least once on the handle. |
|
220 |
|
221 <p>If the kernel returns an indication that there is data ready on the |
|
222 file descriptor, a call to dtn_recv will then return the bundle |
|
223 ithout blocking, then dtn_poll must be called again to wait for |
|
224 more bundles. |
|
225 |
|
226 <p>Also, no other API calls besides dtn_recv can be executed during a |
|
227 polling period, so an app must call dtn_cancel_poll before trying |
|
228 to run other API calls. |
|
229 |
|
230 <tr> |
|
231 <td>Cancel a polling interval. |
|
232 <td><tt>extern int dtn_cancel_poll(dtn_handle_t handle);</tt> |
|
233 <td>TBC |
|
234 <td>None |
|
235 </table> |
|
236 |
|
237 <a name="Utility functions"/> |
|
238 <h3>Utility Functions</h3> |
|
239 |
|
240 <p> |
|
241 <table> |
|
242 <tr> |
|
243 <th>Interface |
|
244 <th>Function |
|
245 <th>Returns |
|
246 <th>Comments |
|
247 |
|
248 <tr> |
|
249 <td>Copy the contents of one eid into another. |
|
250 <td><tt>extern void dtn_copy_eid(dtn_endpoint_id_t* dst, dtn_endpoint_id_t* src);</tt> |
|
251 <td>TBC |
|
252 <td>None |
|
253 |
|
254 <tr> |
|
255 <td>Parse a string into an endpoint id structure. |
|
256 <td><tt>extern int dtn_parse_eid_string(dtn_endpoint_id_t* eid, const char* str);</tt> |
|
257 <td>TBC |
|
258 <td>Parse a string into an endpoint id structure, validating that it is |
|
259 in fact a valid endpoint id (i.e. a URI |
|
260 |
|
261 <tr> |
|
262 <td>Set the value of the given payload structure |
|
263 <td><tt>extern int dtn_set_payload(dtn_bundle_payload_t* payload, |
|
264 dtn_bundle_payload_location_t location, |
|
265 char* val, int len);</tt> |
|
266 <td> 0 | DTN_ESIZE |
|
267 <td>Set the value of the given payload structure to either a memory |
|
268 buffer or a file location.Returns: 0 on success, DTN_ESIZE if the memory location is |
|
269 selected and the payload is too big. |
|
270 |
|
271 |
|
272 |
|
273 <tr> |
|
274 <td>Free dynamic storage. |
|
275 <td><tt>void dtn_free_payload(dtn_bundle_payload_t* payload);</tt> |
|
276 <td>TBC |
|
277 <td>Frees dynamic storage allocated by the xdr for a bundle payload in dtn_recv. |
|
278 |
|
279 <tr> |
|
280 <td>Return a string version of a status report reason code. |
|
281 <td><tt>const char* dtn_status_report_reason_to_str(dtn_status_report_reason_t err);</tt> |
|
282 <td>String |
|
283 <td>None |
|
284 </table> |
|
285 </body> |
|
286 </html> |
|
287 |