dtn_api.h File Reference

#include "dtn_errno.h"
#include "dtn_types.h"

Go to the source code of this file.

Typedefs

typedef int * dtn_handle_t
 The basic handle for communication with the dtn router.

Functions

int dtn_open (dtn_handle_t *handle)
 Open a new connection to the router.
int dtn_close (dtn_handle_t handle)
 Close an open dtn handle.
int dtn_errno (dtn_handle_t handle)
 Get the error associated with the given handle.
void dtn_set_errno (dtn_handle_t handle, int err)
 Set the error associated with the given handle.
int dtn_build_local_eid (dtn_handle_t handle, dtn_endpoint_id_t *local_eid, const char *service_tag)
 Build an appropriate local endpoint id by appending the specified service tag to the daemon's preferred administrative endpoint id.
int dtn_register (dtn_handle_t handle, dtn_reg_info_t *reginfo, dtn_reg_id_t *newregid)
 Create a dtn registration.
int dtn_unregister (dtn_handle_t handle, dtn_reg_id_t regid)
 Remove a dtn registration.
int dtn_find_registration (dtn_handle_t handle, dtn_endpoint_id_t *eid, dtn_reg_id_t *newregid)
 Check for an existing registration on the given endpoint id, returning DTN_SUCCSS and filling in the registration id if it exists, or returning ENOENT if it doesn't.
int dtn_change_registration (dtn_handle_t handle, dtn_reg_id_t regid, dtn_reg_info_t *reginfo)
 Modify an existing registration.
int dtn_bind (dtn_handle_t handle, dtn_reg_id_t regid)
 Associate a registration with the current ipc channel.
int dtn_unbind (dtn_handle_t handle, dtn_reg_id_t regid)
 Explicitly remove an association from the current ipc handle.
int dtn_send (dtn_handle_t handle, dtn_reg_id_t regid, dtn_bundle_spec_t *spec, dtn_bundle_payload_t *payload, dtn_bundle_id_t *id)
 Send a bundle either from memory or from a file.
int dtn_cancel (dtn_handle_t handle, dtn_bundle_id_t *id)
 Cancel a bundle transmission.
int dtn_recv (dtn_handle_t handle, dtn_bundle_spec_t *spec, dtn_bundle_payload_location_t location, dtn_bundle_payload_t *payload, dtn_timeval_t timeout)
 Blocking receive for a bundle, filling in the spec and payload structures with the bundle data.
int dtn_session_update (dtn_handle_t handle, unsigned int *status, dtn_endpoint_id_t *session, dtn_timeval_t timeout)
 Blocking query for new subscribers on a session.
int dtn_poll_fd (dtn_handle_t handle)
 Return a file descriptor for the given handle suitable for calling poll() or select() in conjunction with a call to dtn_begin_poll().
int dtn_begin_poll (dtn_handle_t handle, dtn_timeval_t timeout)
 Begin a polling period for incoming bundles.
int dtn_cancel_poll (dtn_handle_t handle)
 Cancel a polling interval.
void dtn_copy_eid (dtn_endpoint_id_t *dst, dtn_endpoint_id_t *src)
 Copy the contents of one eid into another.
int dtn_parse_eid_string (dtn_endpoint_id_t *eid, const char *str)
 Parse a string into an endpoint id structure, validating that it is in fact a valid endpoint id (i.e.
int dtn_set_payload (dtn_bundle_payload_t *payload, dtn_bundle_payload_location_t location, char *val, int len)
 Sets the value of the given payload structure to either a memory buffer or a file location.
void dtn_free_payload (dtn_bundle_payload_t *payload)
 Frees dynamic storage allocated by the xdr for a bundle payload in dtn_recv.
const char * dtn_status_report_reason_to_str (dtn_status_report_reason_t err)
 Return a string version of a status report reason code.


Typedef Documentation

typedef int* dtn_handle_t

The basic handle for communication with the dtn router.

Definition at line 26 of file dtn_api.h.


Function Documentation

int dtn_begin_poll ( dtn_handle_t  handle,
dtn_timeval_t  timeout 
)

Begin a polling period for incoming bundles.

Returns a file descriptor suitable for calling poll() or select() on (similar to dtn_poll_fd). Note that dtn_bind() must have been previously called at least once on the handle.

If the kernel returns an indication that there is data ready on the file descriptor, a call to dtn_recv will then return the bundle without blocking, then dtn_poll must be called again to wait for more bundles.

Also, no other API calls besides dtn_recv can be executed during a polling period, so an app must call dtn_cancel_poll before trying to run other API calls.

Definition at line 604 of file dtn_api.c.

References DTN_BEGIN_POLL, DTN_EINPOLL, DTN_EXDR, dtnipc_send(), dtnipc_handle::err, handle, dtnipc_handle::in_poll, dtnipc_handle::sock, xdr_dtn_timeval_t(), and dtnipc_handle::xdr_encode.

Referenced by _wrap_dtn_begin_poll(), dtn_begin_poll(), DTNBeginPollCommand::exec(), and XS().

int dtn_bind ( dtn_handle_t  handle,
dtn_reg_id_t  regid 
)

Associate a registration with the current ipc channel.

This serves to put the registration in "active" mode.

Definition at line 305 of file dtn_api.c.

References DTN_BIND, DTN_EINPOLL, DTN_EXDR, dtnipc_send_recv(), dtnipc_handle::err, handle, dtnipc_handle::in_poll, xdr_dtn_reg_id_t(), and dtnipc_handle::xdr_encode.

Referenced by _wrap_dtn_bind(), dtn_bind(), DTNBindCommand::exec(), dtntunnel::DTNTunnel::init_registration(), main(), make_registration(), to_bundles(), and XS().

int dtn_build_local_eid ( dtn_handle_t  handle,
dtn_endpoint_id_t local_eid,
const char *  service_tag 
)

int dtn_cancel ( dtn_handle_t  handle,
dtn_bundle_id_t id 
)

int dtn_cancel_poll ( dtn_handle_t  handle  ) 

int dtn_change_registration ( dtn_handle_t  handle,
dtn_reg_id_t  regid,
dtn_reg_info_t reginfo 
)

Modify an existing registration.

Definition at line 283 of file dtn_api.c.

References DTN_EINPOLL, DTN_EINTERNAL, dtnipc_handle::err, handle, and dtnipc_handle::in_poll.

Referenced by _wrap_dtn_change_registration(), dtn_change_registration(), main(), and XS().

int dtn_close ( dtn_handle_t  handle  ) 

Close an open dtn handle.

Returns DTN_SUCCESS on success.

Definition at line 65 of file dtn_api.c.

References DTN_SUCCESS, and dtnipc_close().

Referenced by _wrap_dtn_close(), dtn_close(), DTNCloseCommand::exec(), dtntunnel::DTNTunnel::main(), main(), reader_thread(), XS(), and TcaController::~TcaController().

void dtn_copy_eid ( dtn_endpoint_id_t dst,
dtn_endpoint_id_t src 
)

int dtn_errno ( dtn_handle_t  handle  ) 

int dtn_find_registration ( dtn_handle_t  handle,
dtn_endpoint_id_t eid,
dtn_reg_id_t newregid 
)

Check for an existing registration on the given endpoint id, returning DTN_SUCCSS and filling in the registration id if it exists, or returning ENOENT if it doesn't.

Definition at line 235 of file dtn_api.c.

References DTN_EINPOLL, DTN_EXDR, DTN_FIND_REGISTRATION, DTN_SUCCESS, dtnipc_recv(), dtnipc_send(), dtnipc_handle::err, handle, dtnipc_handle::in_poll, dtnipc_handle::xdr_decode, xdr_dtn_endpoint_id_t(), xdr_dtn_reg_id_t(), and dtnipc_handle::xdr_encode.

Referenced by _wrap_dtn_find_registration(), dtn_find_registration(), dtntunnel::DTNTunnel::init_registration(), main(), make_registration(), and XS().

void dtn_free_payload ( dtn_bundle_payload_t payload  ) 

Frees dynamic storage allocated by the xdr for a bundle payload in dtn_recv.

Definition at line 736 of file dtn_api.c.

References xdr_dtn_bundle_payload_t().

Referenced by dtn_recv(), DTNRecvCommand::exec(), dtntunnel::DTNTunnel::main(), and main().

int dtn_open ( dtn_handle_t handle  ) 

Open a new connection to the router.

On success, initializes the handle parameter as a new handle to the daemon and returns DTN_SUCCESS. On failure, sets handle to NULL and returns a dtn_errno error code.

Definition at line 39 of file dtn_api.c.

References DTN_EINTERNAL, DTN_SUCCESS, dtnipc_open(), dtnipc_handle::err, handle, dtnipc_handle::xdr_decode, and dtnipc_handle::xdr_encode.

Referenced by _wrap_dtn_open(), dtn_open(), DTNOpenCommand::exec(), TcaController::init(), dtntunnel::DTNTunnel::init_registration(), main(), reader_thread(), and XS().

int dtn_parse_eid_string ( dtn_endpoint_id_t eid,
const char *  str 
)

Parse a string into an endpoint id structure, validating that it is in fact a valid endpoint id (i.e.

a URI).

Definition at line 681 of file dtn_api.c.

References DTN_EINVAL, DTN_ESIZE, DTN_MAX_ENDPOINT_ID, len, and dtn_endpoint_id_t::uri.

Referenced by main(), make_spec(), parse_eid(), TcaController::send_bundle(), dtn::APIEndpointIDOpt::set(), and dtntunnel::DTNTunnel::validate_options().

int dtn_poll_fd ( dtn_handle_t  handle  ) 

Return a file descriptor for the given handle suitable for calling poll() or select() in conjunction with a call to dtn_begin_poll().

Definition at line 596 of file dtn_api.c.

References handle, and dtnipc_handle::sock.

Referenced by _wrap_dtn_poll_fd(), dtn_poll_fd(), DTNPollChannelCommand::exec(), and XS().

int dtn_recv ( dtn_handle_t  handle,
dtn_bundle_spec_t spec,
dtn_bundle_payload_location_t  location,
dtn_bundle_payload_t payload,
dtn_timeval_t  timeout 
)

Blocking receive for a bundle, filling in the spec and payload structures with the bundle data.

The location parameter indicates the manner by which the caller wants to receive payload data (i.e. either in memory or in a file). The timeout parameter specifies an interval in milliseconds to block on the server-side (-1 means infinite wait).

Note that it is advisable to call dtn_free_payload on the returned structure, otherwise the XDR routines will memory leak.

Definition at line 430 of file dtn_api.c.

References dtn_bundle_payload_t::buf, dtn_bundle_payload_t::buf_len, dtn_bundle_payload_t::buf_val, DTN_EXDR, dtn_free_payload(), DTN_PAYLOAD_FILE, DTN_PAYLOAD_MEM, DTN_RECV, DTN_SUCCESS, dtnipc_recv(), dtnipc_send_recv(), dtnipc_handle::err, errno, fd, dtn_bundle_payload_t::filename, filename, dtn_bundle_payload_t::filename_val, handle, dtnipc_handle::in_poll, len, dtn_bundle_payload_t::location, PATH_MAX, dtnipc_handle::xdr_decode, xdr_dtn_bundle_payload_location_t(), xdr_dtn_bundle_payload_t(), xdr_dtn_bundle_spec_t(), xdr_dtn_timeval_t(), and dtnipc_handle::xdr_encode.

Referenced by _wrap_dtn_recv(), dtn_recv(), TcaController::eat_bundles(), DTNRecvCommand::exec(), from_bundles(), dtntunnel::DTNTunnel::main(), main(), TcaController::recv_bundle(), to_bundles(), and XS().

int dtn_register ( dtn_handle_t  handle,
dtn_reg_info_t reginfo,
dtn_reg_id_t newregid 
)

Create a dtn registration.

If the init_passive flag in the reginfo struct is true, the registration is initially in passive state, requiring a call to dtn_bind to activate it. Otherwise, the call to dtn_bind is unnecessary as the registration will be created in the active state and bound to the handle.

Definition at line 147 of file dtn_api.c.

References DTN_EINPOLL, DTN_EXDR, DTN_REGISTER, DTN_SUCCESS, dtnipc_recv(), dtnipc_send(), dtnipc_handle::err, handle, dtnipc_handle::in_poll, dtnipc_handle::xdr_decode, xdr_dtn_reg_id_t(), xdr_dtn_reg_info_t(), and dtnipc_handle::xdr_encode.

Referenced by _wrap_dtn_register(), TcaController::dtn_reg(), dtn_register(), DTNRegisterCommand::exec(), dtntunnel::DTNTunnel::init_registration(), main(), make_registration(), reader_thread(), and XS().

int dtn_send ( dtn_handle_t  handle,
dtn_reg_id_t  regid,
dtn_bundle_spec_t spec,
dtn_bundle_payload_t payload,
dtn_bundle_id_t id 
)

int dtn_session_update ( dtn_handle_t  handle,
unsigned int *  status,
dtn_endpoint_id_t session,
dtn_timeval_t  timeout 
)

Blocking query for new subscribers on a session.

One or more registrations must have been bound to the handle with the SESSION_CUSTODY flag set. Returns an indication that the subscription state in the given session has changed (i.e. a subscriber was added or removed).

Definition at line 545 of file dtn_api.c.

References DTN_EXDR, DTN_SESSION_UPDATE, DTN_SUCCESS, dtnipc_recv(), dtnipc_send_recv(), dtnipc_handle::err, handle, dtnipc_handle::in_poll, dtnipc_handle::xdr_decode, xdr_dtn_endpoint_id_t(), xdr_dtn_timeval_t(), and dtnipc_handle::xdr_encode.

Referenced by _wrap_dtn_session_update(), dtn_session_update(), DTNSessionUpdateCommand::exec(), and XS().

void dtn_set_errno ( dtn_handle_t  handle,
int  err 
)

Set the error associated with the given handle.

Definition at line 81 of file dtn_api.c.

Referenced by dtn_recv(), and dtn_send().

int dtn_set_payload ( dtn_bundle_payload_t payload,
dtn_bundle_payload_location_t  location,
char *  val,
int  len 
)

Sets the value of the given payload structure to either a memory buffer or a file location.

Returns: 0 on success, DTN_ESIZE if the memory location is selected and the payload is too big.

Definition at line 708 of file dtn_api.c.

References dtn_bundle_payload_t::buf, dtn_bundle_payload_t::buf_len, dtn_bundle_payload_t::buf_val, DTN_ESIZE, DTN_MAX_BUNDLE_MEM, DTN_PAYLOAD_FILE, DTN_PAYLOAD_MEM, DTN_PAYLOAD_TEMP_FILE, dtn_bundle_payload_t::filename, dtn_bundle_payload_t::filename_len, dtn_bundle_payload_t::filename_val, and dtn_bundle_payload_t::location.

Referenced by DTNSendCommand::exec(), fill_payload(), main(), reader_thread(), TcaController::send_bundle(), and dtntunnel::DTNTunnel::send_bundle().

const char* dtn_status_report_reason_to_str ( dtn_status_report_reason_t  err  ) 

int dtn_unbind ( dtn_handle_t  handle,
dtn_reg_id_t  regid 
)

Explicitly remove an association from the current ipc handle.

Note that this is also implicitly done when the handle is closed.

This serves to put the registration back in "passive" mode.

Definition at line 332 of file dtn_api.c.

References DTN_EINPOLL, DTN_EXDR, DTN_UNBIND, dtnipc_send_recv(), dtnipc_handle::err, handle, dtnipc_handle::in_poll, xdr_dtn_reg_id_t(), and dtnipc_handle::xdr_encode.

Referenced by _wrap_dtn_unbind(), dtn_unbind(), DTNUnbindCommand::exec(), and XS().

int dtn_unregister ( dtn_handle_t  handle,
dtn_reg_id_t  regid 
)

Remove a dtn registration.

If the registration is in the passive state (i.e. not bound to any handle), it is immediately removed from the system. If it is in active state and bound to the given handle, the removal is deferred until the handle unbinds the registration or closes. This allows applications to pre-emptively call unregister so they don't leak registrations.

Definition at line 195 of file dtn_api.c.

References DTN_EINPOLL, DTN_EXDR, DTN_SUCCESS, DTN_UNREGISTER, dtnipc_recv(), dtnipc_send(), dtnipc_handle::err, handle, dtnipc_handle::in_poll, xdr_dtn_reg_id_t(), and dtnipc_handle::xdr_encode.

Referenced by _wrap_dtn_unregister(), dtn_unregister(), DTNUnregisterCommand::exec(), main(), and XS().


Generated on Fri Jan 30 09:26:59 2009 for DTN Reference Implementation by  doxygen 1.5.8