|
1 /* |
|
2 * Copyright 2004-2006 Intel Corporation |
|
3 * |
|
4 * Licensed under the Apache License, Version 2.0 (the "License"); |
|
5 * you may not use this file except in compliance with the License. |
|
6 * You may obtain a copy of the License at |
|
7 * |
|
8 * http://www.apache.org/licenses/LICENSE-2.0 |
|
9 * |
|
10 * Unless required by applicable law or agreed to in writing, software |
|
11 * distributed under the License is distributed on an "AS IS" BASIS, |
|
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
|
13 * See the License for the specific language governing permissions and |
|
14 * limitations under the License. |
|
15 */ |
|
16 |
|
17 #ifndef DTN_API_H |
|
18 #define DTN_API_H |
|
19 |
|
20 #include "dtn_errno.h" |
|
21 #include "dtn_types.h" |
|
22 |
|
23 /** |
|
24 * The basic handle for communication with the dtn router. |
|
25 */ |
|
26 typedef int* dtn_handle_t; |
|
27 |
|
28 #ifdef __cplusplus |
|
29 extern "C" { |
|
30 #endif |
|
31 |
|
32 /************************************************************* |
|
33 * |
|
34 * API Functions |
|
35 * |
|
36 *************************************************************/ |
|
37 |
|
38 /** |
|
39 * Open a new connection to the router. |
|
40 * |
|
41 * On success, initializes the handle parameter as a new handle to the |
|
42 * daemon and returns DTN_SUCCESS. On failure, sets handle to NULL and |
|
43 * returns a dtn_errno error code. |
|
44 */ |
|
45 extern int dtn_open(dtn_handle_t* handle); |
|
46 |
|
47 /** |
|
48 * Close an open dtn handle. Returns DTN_SUCCESS on success. |
|
49 */ |
|
50 extern int dtn_close(dtn_handle_t handle); |
|
51 |
|
52 /** |
|
53 * Get the error associated with the given handle. |
|
54 */ |
|
55 extern int dtn_errno(dtn_handle_t handle); |
|
56 |
|
57 /** |
|
58 * Set the error associated with the given handle |
|
59 */ |
|
60 extern void dtn_set_errno(dtn_handle_t handle, int err); |
|
61 |
|
62 /** |
|
63 * Build an appropriate local endpoint id by appending the specified |
|
64 * service tag to the daemon's preferred administrative endpoint id. |
|
65 */ |
|
66 extern int dtn_build_local_eid(dtn_handle_t handle, |
|
67 dtn_endpoint_id_t* local_eid, |
|
68 const char* service_tag); |
|
69 |
|
70 /** |
|
71 * Create a dtn registration. If the init_passive flag in the reginfo |
|
72 * struct is true, the registration is initially in passive state, |
|
73 * requiring a call to dtn_bind to activate it. Otherwise, the call to |
|
74 * dtn_bind is unnecessary as the registration will be created in the |
|
75 * active state and bound to the handle. |
|
76 */ |
|
77 extern int dtn_register(dtn_handle_t handle, |
|
78 dtn_reg_info_t* reginfo, |
|
79 dtn_reg_id_t* newregid); |
|
80 |
|
81 /** |
|
82 * Remove a dtn registration. |
|
83 * |
|
84 * If the registration is in the passive state (i.e. not bound to any |
|
85 * handle), it is immediately removed from the system. If it is in |
|
86 * active state and bound to the given handle, the removal is deferred |
|
87 * until the handle unbinds the registration or closes. This allows |
|
88 * applications to pre-emptively call unregister so they don't leak |
|
89 * registrations. |
|
90 */ |
|
91 extern int dtn_unregister(dtn_handle_t handle, |
|
92 dtn_reg_id_t regid); |
|
93 |
|
94 /** |
|
95 * Check for an existing registration on the given endpoint id, |
|
96 * returning DTN_SUCCSS and filling in the registration id if it |
|
97 * exists, or returning ENOENT if it doesn't. |
|
98 */ |
|
99 extern int dtn_find_registration(dtn_handle_t handle, |
|
100 dtn_endpoint_id_t* eid, |
|
101 dtn_reg_id_t* newregid); |
|
102 |
|
103 /** |
|
104 * Modify an existing registration. |
|
105 */ |
|
106 extern int dtn_change_registration(dtn_handle_t handle, |
|
107 dtn_reg_id_t regid, |
|
108 dtn_reg_info_t *reginfo); |
|
109 |
|
110 /** |
|
111 * Associate a registration with the current ipc channel. |
|
112 * This serves to put the registration in "active" mode. |
|
113 */ |
|
114 extern int dtn_bind(dtn_handle_t handle, dtn_reg_id_t regid); |
|
115 |
|
116 /** |
|
117 * Explicitly remove an association from the current ipc handle. Note |
|
118 * that this is also implicitly done when the handle is closed. |
|
119 * |
|
120 * This serves to put the registration back in "passive" mode. |
|
121 */ |
|
122 extern int dtn_unbind(dtn_handle_t handle, dtn_reg_id_t regid); |
|
123 |
|
124 /** |
|
125 * Send a bundle either from memory or from a file. |
|
126 */ |
|
127 extern int dtn_send(dtn_handle_t handle, |
|
128 dtn_reg_id_t regid, |
|
129 dtn_bundle_spec_t* spec, |
|
130 dtn_bundle_payload_t* payload, |
|
131 dtn_bundle_id_t* id); |
|
132 |
|
133 /** |
|
134 * Cancel a bundle transmission. |
|
135 */ |
|
136 extern int dtn_cancel(dtn_handle_t handle, |
|
137 dtn_bundle_id_t* id); |
|
138 |
|
139 /** |
|
140 * Blocking receive for a bundle, filling in the spec and payload |
|
141 * structures with the bundle data. The location parameter indicates |
|
142 * the manner by which the caller wants to receive payload data (i.e. |
|
143 * either in memory or in a file). The timeout parameter specifies an |
|
144 * interval in milliseconds to block on the server-side (-1 means |
|
145 * infinite wait). |
|
146 * |
|
147 * Note that it is advisable to call dtn_free_payload on the returned |
|
148 * structure, otherwise the XDR routines will memory leak. |
|
149 */ |
|
150 extern int dtn_recv(dtn_handle_t handle, |
|
151 dtn_bundle_spec_t* spec, |
|
152 dtn_bundle_payload_location_t location, |
|
153 dtn_bundle_payload_t* payload, |
|
154 dtn_timeval_t timeout); |
|
155 |
|
156 /** |
|
157 * Blocking query for new subscribers on a session. One or more |
|
158 * registrations must have been bound to the handle with the |
|
159 * SESSION_CUSTODY flag set. Returns an indication that the |
|
160 * subscription state in the given session has changed (i.e. a |
|
161 * subscriber was added or removed). |
|
162 */ |
|
163 extern int dtn_session_update(dtn_handle_t handle, |
|
164 unsigned int* status, |
|
165 dtn_endpoint_id_t* session, |
|
166 dtn_timeval_t timeout); |
|
167 |
|
168 /** |
|
169 * Return a file descriptor for the given handle suitable for calling |
|
170 * poll() or select() in conjunction with a call to dtn_begin_poll(). |
|
171 */ |
|
172 extern int dtn_poll_fd(dtn_handle_t handle); |
|
173 |
|
174 /** |
|
175 * Begin a polling period for incoming bundles. Returns a file |
|
176 * descriptor suitable for calling poll() or select() on (similar to |
|
177 * dtn_poll_fd). Note that dtn_bind() must have been previously called |
|
178 * at least once on the handle. |
|
179 * |
|
180 * If the kernel returns an indication that there is data ready on the |
|
181 * file descriptor, a call to dtn_recv will then return the bundle |
|
182 * without blocking, then dtn_poll must be called again to wait for |
|
183 * more bundles. |
|
184 * |
|
185 * Also, no other API calls besides dtn_recv can be executed during a |
|
186 * polling period, so an app must call dtn_cancel_poll before trying |
|
187 * to run other API calls. |
|
188 */ |
|
189 extern int dtn_begin_poll(dtn_handle_t handle, dtn_timeval_t timeout); |
|
190 |
|
191 /** |
|
192 * Cancel a polling interval. |
|
193 */ |
|
194 extern int dtn_cancel_poll(dtn_handle_t handle); |
|
195 |
|
196 /************************************************************* |
|
197 * |
|
198 * Utility Functions |
|
199 * |
|
200 *************************************************************/ |
|
201 |
|
202 /** |
|
203 * Copy the contents of one eid into another. |
|
204 */ |
|
205 extern void dtn_copy_eid(dtn_endpoint_id_t* dst, dtn_endpoint_id_t* src); |
|
206 |
|
207 /** |
|
208 * Parse a string into an endpoint id structure, validating that it is |
|
209 * in fact a valid endpoint id (i.e. a URI). |
|
210 */ |
|
211 extern int dtn_parse_eid_string(dtn_endpoint_id_t* eid, const char* str); |
|
212 |
|
213 /** |
|
214 * Sets the value of the given payload structure to either a memory |
|
215 * buffer or a file location. |
|
216 * |
|
217 * Returns: 0 on success, DTN_ESIZE if the memory location is |
|
218 * selected and the payload is too big. |
|
219 */ |
|
220 extern int dtn_set_payload(dtn_bundle_payload_t* payload, |
|
221 dtn_bundle_payload_location_t location, |
|
222 char* val, int len); |
|
223 |
|
224 /** |
|
225 * Frees dynamic storage allocated by the xdr for a bundle payload in |
|
226 * dtn_recv. |
|
227 */ |
|
228 void dtn_free_payload(dtn_bundle_payload_t* payload); |
|
229 |
|
230 /** |
|
231 * Return a string version of a status report reason code. |
|
232 */ |
|
233 const char* dtn_status_report_reason_to_str(dtn_status_report_reason_t err); |
|
234 |
|
235 #ifdef __cplusplus |
|
236 } |
|
237 #endif |
|
238 |
|
239 #endif /* DTN_API_H */ |