DBL: DBL API Documentation

#define DBL_VERSION_API 0x0001

DBL API version number (16 bits) Least significant byte increases for minor backwards compatible changes in the API. Most significant byte increases for incompatible changes in the API

enum dbl_recvmode

Specifies behavior of the dbl_recvfrom call

Enumerator:

DBL_RECV_DEFAULT	Busy poll forever until a packet is received.
DBL_RECV_NONBLOCK	Return a packet if available, else return EAGAIN.
DBL_RECV_BLOCK	Block until a packet is available, sleep until interrupt if necessary.
DBL_RECV_PEEK	Check for a packet one time, return info, or EAGAIN if no packet.
DBL_RECV_PEEK_MSG	Peek but also copy data, return info, or EAGAIN if no packet.

dbl_bind	(	dbl_device_t	dev,
		int	flags,
		int	port,
		void *	context,
		dbl_channel_t *	handle_out
	)

Create a channel on dbl device.

Creates a channel on a specified device through which UDP datagrams may be sent and received. Any packets sent through this channel will have "port" as their source port and packets arriving on the interface addressed to "port" will be received on this channel. By default, only unicast packets, not broadcast or multicast, will be received on the channel.

Parameters:

	dev	A DBL device handle returned by a call to dbl_open().
	flags	See Flags used for dbl_bind().
	port	The port to send/receive on.
	context	The value of context is returned on future receives on this channel.
	handle_out	The handle to the created channel.

Return values:

	0	Success
	EINVAL	Error in arguments
	EEXIST	port already in use
	?	Other values indicate various OS failures in the bind process

If dbl_bind() is called multiple times on the same port on a single device, unicast packets will only be delivered to the oldest channel currently bound to the port.

dbl_bind_addr	(	dbl_device_t	dev,
		struct in_addr *	ipaddr,
		int	flags,
		int	port,
		void *	context,
		dbl_channel_t *	handle_out
	)

Creates a channel, using specified ip address.

Creates a channel on a specified device, just like dbl_bind, except that it associates the channel with the specified address instead of the one specified in the dbl_open call.

The address used must correspond to an OS-level interface that maps to the same underlying Ethernet port as the interface specified in dbl_open. For example, this can be a VLAN interface.

Parameters:

	dev	A DBL device handle returned by a call to dbl_open().
	interface_addr	Specifies the IP address of the interface with which the channel created will be associated. This must be on the same underlying interface as the one used in the dbl_open call.
	flags	See Flags used for dbl_bind().
	port	The port to send/receive on.
	context	The value of context is returned on future receives on this channel.
	handle_out	The handle to the created channel.

Return values:

	0	Success
	EINVAL	Error in arguments. Specifying an address that is not on the same underlying interface as that specified with dbl_open will return EINVAL.
	EEXIST	port already in use
	?	Other values indicate various OS failures in the bind process

dbl_close ( dbl_device_t dev )

Close a dbl device.

Terminate usage of a device returned by dbl_open() and free all resources associated with it.

Parameters:

dev

The device handle returned from dbl_open().

Return values:

0

Success

dbl_device_handle ( dbl_device_t dev )

Returns a descriptor for use with poll() or select().

Returns an OS-specific file descriptor which can be passed to poll() or select() to block on receive data available. For UNIX systems. this is a file descriptor, on Windows it is a HANDLE.

Parameters:

dev

The DBL device whose OS handle is needed.

Returns:: OS-specific handle for device

dbl_getaddress	(	dbl_channel_t	ch,
		struct sockaddr_in *	sin
	)

Returns the address to which a channel is bound.

Parameters:

	ch	Specifes the channel whose bind information is required.
	sin	sockaddr_in to which the address will be copied out.

Return values:

	0	Sucess
	EINVAL	Bad channel specified

dbl_init ( uint16_t api_version )

Initializes the dbl library.

Parameters:

api_version

Must always be DBL_VERSION_API. This is used to ensure compatability between the application binary and the DBL library.

Return values:

	0	Success
	EINVAL	Bad/incompatible version passed.

Remarks:: dbl_init() must be called once at the start of any application that uses DBL.

dbl_mcast_join	(	dbl_channel_t	ch,
		struct in_addr *	mcast_addr,
		void *	unused
	)

Join a multicast group.

Indicates that the specified channel wishes to receive packets addressed to the multicast address specified.

Parameters:

	ch	Handle for the channel to add to the specified multicast group.
	mcast_addr	Address of the multicast group to join.
	unused	A temporary unused pointer to maintain binary compability.

Return values:

	0	Success
	EINVAL	Argument error, such as address is not a multicast group.
	?	Other values indicate various OS specific failures in the join process.

dbl_mcast_leave	(	dbl_channel_t	ch,
		struct in_addr *	mcast_addr
	)

Leave a multicast group.

Indicates that the specified channel wishes to stop receiving packets addressed to the multicast address specified.

Parameters:

	ch	Handle for the channel to leave the specified multicast group.
	mcast_addr	Address of the multicast group to leave.

Return values:

	0	Success
	EINVAL	Argument error, such as address not multicast group.
	EADDRNOTAVAIL	Not currently joined to group "address"
	EAGAIN	internal resources temorarily unavailable, try again.
	?	Other non-zero codes indicate various OS failures in the leave process

dbl_open	(	struct in_addr *	interface_addr,
		int	flags,
		dbl_device_t *	dev_out
	)

Creates an instance of a dbl_device.

Creates an instance of a dbl device which can be used to subsequently open channels via dbl_bind().

Parameters:

	interface_addr	Specifies the IP address of the interface with which channels created using dbl_bind() will be associated.
	flags	A bitmask of flags to alter open behavior. See Flags used for dbl_open()
	dev_out	On successful return, this is where the handle for the newly opened device will be placed.

Return values:

	0	Success
	EINVAL	bad usage. includes dbl_init not called first and bad interface_addr.
	ENODEV	no matching IP address found on DBL-enabled NIC
	EAGAIN	internal resources temorarily unavailable, try again.

Remarks:: Unlike traditional sockets, a DBL channel cannot be associated with multiple network interfaces.

dbl_open_if	(	const char *	ifname,
		int	flags,
		dbl_device_t *	dev_out
	)

Creates an instance of a dbl_device.

Like dbl_open () except it takes an interface name instead of an ip address.

Parameters:

	ifname	Specifies the name of the interface with which channels created using dbl_bind() will be associated.
	flags	A bitmask of flags to alter open behavior. See Flags used for dbl_open()
	dev_out	On successful return, this is where the handle for the newly opened device will be placed.

Return values:

	0	Success
	EINVAL	bad usage. includes dbl_init not called first and bad interface_addr.
	EAGAIN	internal resources temorarily unavailable, try again.

Remarks:: Unlike traditional sockets, a DBL channel cannot be associated with multiple network interfaces.

dbl_recvfrom	(	dbl_device_t	dev,
		enum dbl_recvmode	mode,
		void *	buf,
		size_t	len,
		struct dbl_recv_info *	info
	)

Receive data.

Used to check for and read data from the channels associated with a particular dbl_device.

Parameters:

	dev	The channel (from dbl_bind()) on which a packet has been received.
	mode	See dbl_recvmode
	buf	Buffer in which to place received data.
	len	Maximum number of bytes to write into buf.
	info	See dbl_recv_info.

Return values:

	0	Success
	EAGAIN	Returned if using mode DBL_RECV_NONBLOCK or DBL_RECV_PEEK when no packet is available.
	?	Other codes indicate various OS failures.

Remarks:: dbl_recvfrom() will, by default, busy-poll checking for data available on the device. This consumes 100% of the CPU available to this single thread, but also guarantees the lowest possible latency for packet delivery. A blocking mode of operation may be speficied through the recv_mode parameter, reducing CPU load at the expense of a few microseconds of message latency.

dbl_send	(	dbl_send_t	sendh,
		const void *	buf,
		size_t	len,
		int	flags
	)

Send a packet using a send handle.

Sends a packet to the address associated with the specified send handle. The send_handle must have been previously created by a call to dbl_send_connect(). If internal resources are unvailable to execute the send immediately, the send call will block until resources are available to proceed.

Parameters:

	sendh	Send handle specifying destination for packe.
	buf	The data to send.
	len	The number of bytes to send.
	flags	See Flags for dbl_send()..

Return values:

	0	Success
	EAGAIN	DBL_NONBLOCK specified and no resources available.
	?	Other codes indicate various OS failures in the send process.

dbl_send_connect	(	dbl_channel_t	chan,
		const struct sockaddr_in *	dest_sin,
		int	flags,
		int	ttl,
		dbl_send_t *	hsend
	)

Create a send_handle for faster sending.

Used to create a send handle for fast sending to a remote destination.

Parameters:

	chan	The channel to be associated with this send handle.
	dest_sin	Destination address of packets sent using this handle.
	flags	Bitmask of flags to modify default send_connect operation Currently no flags are supported.
	ttl	The value to put in the TTL field of the IP header.
	hsend	The send_handle to be used in future calls to dbl_send() is returned here.

Return values:

	0	Sucess
	EINVAL	Errors in arguments
	?	Other codes indicate various OS failures in the send process.

Remarks:: The returned send handle is a reference to a set of precomputed data that is needed to send a packet to a particular destination. This precomputed data is saved and cached by DBL as a matter of course through the dbl_sendto() function, but holding a send_handle avoids the need for a hash lookup to find the necessary information. This can take 100-200 ns off the time required to do a send.
Since dbl_send_connect will re-use a cached send handle to the same destination, the ttl parameter, if non-zero, will overwrite the ttl value in the cached sendhandle. This means that any future dbl_sendto operations to the same destination will use the new ttl value. This also means that if there is a need to use dbl_sendto with a different ttl than the default, it is possible to use a call to dbl_send_connect to change the ttl.

dbl_send_disconnect ( dbl_send_t hsend )

Release a send handle.

Release the resources associated with a send handle.

Parameters:

hsend

The send handle.

Return values:

0

Success

dbl_sendto	(	dbl_channel_t	ch,
		struct sockaddr_in *	sin,
		const void *	buf,
		size_t	len,
		int	flags
	)

Send a packet.

Send a packet to the address specified.

Parameters:

	ch	Handle for the channel to send over.
	sin	The destination address
	buf	The data to send.
	len	The lenght of the data to send.
	flags	See Flags for dbl_send().

Return values:

	0	Success
	EAGAIN	DBL_NONBLOCK specified and no resources available.
	?	Other codes indicate various OS failures in the send process.

dbl_unbind ( dbl_channel_t handle )

Destroys a channel.

Destroys a channel and releases all the resources associated with it.

Parameters:

handle

The handle of the channel to unbind.

Return values:

0

Success

API Reference

API Reference

Data Structures

Defines

Enumerations

Functions

Detailed Description

API Reference

Define Documentation

Enumeration Type Documentation

Function Documentation


API Reference
	Flags used for dbl_open()
	Flags used for dbl_bind()
	Flags for dbl_send().
Data Structures
struct	dbl_recv_info
	Information about the packet received. More...
Defines
#define	DBL_VERSION_API 0x0001
Enumerations
enum	dbl_recvmode { DBL_RECV_DEFAULT = 0, DBL_RECV_NONBLOCK = 1, DBL_RECV_BLOCK = 2, DBL_RECV_PEEK = 3, DBL_RECV_PEEK_MSG = 4 }
Functions
	dbl_init (uint16_t api_version)
	Initializes the dbl library.
	dbl_open (struct in_addr interface_addr, int flags, dbl_device_t dev_out)
	Creates an instance of a dbl_device.
	dbl_open_if (const char ifname, int flags, dbl_device_t dev_out)
	Creates an instance of a dbl_device.
	dbl_device_handle (dbl_device_t dev)
	Returns a descriptor for use with poll() or select().
	dbl_close (dbl_device_t dev)
	Close a dbl device.
	dbl_bind (dbl_device_t dev, int flags, int port, void context, dbl_channel_t handle_out)
	Create a channel on dbl device.
	dbl_bind_addr (dbl_device_t dev, struct in_addr ipaddr, int flags, int port, void context, dbl_channel_t *handle_out)
	Creates a channel, using specified ip address.
	dbl_unbind (dbl_channel_t handle)
	Destroys a channel.
	dbl_getaddress (dbl_channel_t ch, struct sockaddr_in *sin)
	Returns the address to which a channel is bound.
	dbl_mcast_join (dbl_channel_t ch, struct in_addr mcast_addr, void unused)
	Join a multicast group.
	dbl_mcast_leave (dbl_channel_t ch, struct in_addr *mcast_addr)
	Leave a multicast group.
	dbl_recvfrom (dbl_device_t dev, enum dbl_recvmode mode, void buf, size_t len, struct dbl_recv_info info)
	Receive data.
	dbl_send_connect (dbl_channel_t chan, const struct sockaddr_in dest_sin, int flags, int ttl, dbl_send_t hsend)
	Create a send_handle for faster sending.
	dbl_send (dbl_send_t sendh, const void *buf, size_t len, int flags)
	Send a packet using a send handle.
	dbl_send_disconnect (dbl_send_t hsend)
	Release a send handle.
	dbl_sendto (dbl_channel_t ch, struct sockaddr_in sin, const void buf, size_t len, int flags)
	Send a packet.