btnut/btnode/include/mhop/mhop_cl.h File Reference


Detailed Description

Implementation of a connectionless multi-hop layer, using the L2CAP connectionless data channel.

Author:
Kevin Martin <kevmarti@tik.ee.ethz.ch>
Date:
2006/03/23
Service Registration
Higher layer services can use the function mhop_cl_send_pkt to send connection-less multi-hop packets to a specific service on the target device. On the receiving side, the service is identified by a unique "PSM" identifier - a number that is included in the multi-hop packet header.

Receiving connection-less multi-hop data packets is the same as receiving point-to-point data packets: higher layer services have to register a service routine together with a PSM identifier at the protocol/service multiplexor (see bt_psm_service_register, l2cap_cl.h).

Packet Forwarding
Forwarding of a packet to its destination node is done by consulting forwarding tables maintained by each node in the network: if a destination can't be found in the table, the packet is discarded.

Routing is done by broadcasting packets: Each node receiving a broadcast packet stores the source node's address together with the connection handle the packet was received on in the forwarding table.
Incoming packets having a target address that matches one of the entries in the forwarding table are then forwarded directely over the corresponding connection handle.

#include <bt/bt_defs.h>
#include <bt/bt_hci_defs.h>
#include <bt/bt_psm.h>

Data Structures

struct  mhop_cl_fwt_entry_s
 Forwarding table entry. More...

Defines

Packet Properties
#define MHOP_CL_BROADCAST   0
 Packet shall be broadcasted.
#define MHOP_CL_TTL_INFINITE   0
 infinite time to live
#define MHOP_CL_UNICAST   1
 Packet shall be forwarded if possible.
Errors
#define MHOP_CL_ERR_FORWARDING   -2
 Packet send error: no corresponding entry found in the forwarding table.
#define MHOP_CL_ERR_PAYLOAD_OVERFLOW   -1
 If amount of data to send is too big.
Forwarding Table Events
#define MHOP_CL_FWT_SOURCE_ADDED   0
 A new source has been added to the forwarding table.
#define MHOP_CL_FWT_SOURCE_DELETED   1
 A source has been deleted from the forwarding table.
#define MHOP_CL_FWTABLE_CB   void (*fwt_cb) (mhop_cl_fwt_entry* entry, u_char type, void* cb_arg)
 Forwarding table changed callback.

Typedefs

typedef mhop_cl_fwt_entry_s mhop_cl_fwt_entry
 Forwarding table entry.

Functions

void mhop_cl_fwt_register_cb (MHOP_CL_FWTABLE_CB, void *cb_arg)
 To register the forwarding table change callback.
u_charmhop_cl_get_my_addr (void)
 Returns the bluetooth address of this device.
u_short mhop_cl_max_payload_size (void)
 Returns the maximal amount of data that can be sent within a single multi-hop packet.
void mhop_cl_register_con_table_cb (HCI_CON_TABLE_CB, void *cb_arg)
Forwarding Table Accessors
mhop_cl_fwt_entrymhop_cl_fwt_get_entry (bt_addr_t addr)
int mhop_cl_fwt_update (bt_addr_t src_addr, bt_hci_con_handle_t src_handle, u_char src_seq, u_char distance)
 Updates the forwarding table.
Packet accessors
u_charmhop_cl_get_source_addr (struct bt_hci_pkt_acl *pkt)
 Returns the source address of a received packet.
u_charmhop_cl_get_target_addr (struct bt_hci_pkt_acl *pkt)
 Returns the target address of an received packet.
Initialization
void mhop_cl_init (struct btstack *bt_stack, bt_psm_t *psmux, u_short psm, u_short buf_size, HCI_CON_TABLE_CB_REGISTRATION)
 Initializes the connection-less multi-hop layer.
Sending multi-hop packets
long mhop_cl_send_pkt (u_char *data, u_short len, bt_addr_t dest, u_short psm, u_char bc_flag, u_char ttl)
 Sends a multi-hop packet to a service on a remote device.
long mhop_cl_send_src_del_pkt (bt_addr_t addr, u_char ttl)
 broadcasts a source deletion packet


Typedef Documentation

typedef struct mhop_cl_fwt_entry_s mhop_cl_fwt_entry

Forwarding table entry.

When receiving a connectionless l2cap packet containing a multi-hop information trailer whos "source record" flag is set (see typedef mhop_cl_mhop_ctrl_info), the address of the sender will be stored in the forwarding table.

Essentially, an entry in the forwarding table consists of the address of the source node, and the connection handle over which the source node can be reached.


Function Documentation

mhop_cl_fwt_entry* mhop_cl_fwt_get_entry ( bt_addr_t  addr  ) 

Returns the forwarding table entry associated with the passed device address.

Scans the forwarding table for an entry containing the destination address dest and returns it.

Parameters:
addr Address of the desired destination node
Returns:
  • the corresponding forwarding table entry
  • NULL else

void mhop_cl_fwt_register_cb ( MHOP_CL_FWTABLE_CB  ,
void *  cb_arg 
)

To register the forwarding table change callback.

This function registers the forwarding table change callback function which is called each time a source has been added to / removed from the forwarding table.

Parameters:
MHOP_CL_FWTABLE_CB Function-Pointer to the callback
cb_arg Some callback argument which is passed to the registering layer each time the callback is called

int mhop_cl_fwt_update ( bt_addr_t  src_addr,
bt_hci_con_handle_t  src_handle,
u_char  src_seq,
u_char  distance 
)

Updates the forwarding table.

Parameters:
src_addr Address of the source
src_handle Handle pkt was received from
src_seq Sequence number of the source broadcast
ttl time to live of the source broadcast
distance Distance to the source

u_char* mhop_cl_get_my_addr ( void   ) 

Returns the bluetooth address of this device.

TODO: move this function to bt_hci.c

void mhop_cl_init ( struct btstack bt_stack,
bt_psm_t psmux,
u_short  psm,
u_short  buf_size,
HCI_CON_TABLE_CB_REGISTRATION   
)

Initializes the connection-less multi-hop layer.

Parameters:
stack Pointer to the bt stack to use
psmux Pointer to the protocol/service multiplexor
mhop_psm PSM the multi-hop layer should use
buf_size Nr of buffers used for buffering packets that have to be forwarded
HCI_CON_TABLE_CB_REGISTRATION defines where the mhop layer has to register its callback function that handles changes in the connection table.
See also:
bt_psm.h
Examples:
mhop_blink/mhop_blink.c.

long mhop_cl_send_pkt ( u_char data,
u_short  len,
bt_addr_t  dest,
u_short  psm,
u_char  bc_flag,
u_char  ttl 
)

Sends a multi-hop packet to a service on a remote device.

This function sends a data packet to a service on a remote device - if necessary via several relay hops.

Set the broadcast flag bc_flag to specify if the packet shall be broadcasted or not:

By specifying dest = bt_addr_null, _all_ devices receiving the packet do deliver the packet to the application layer.

Parameters:
data Pointer to the data to send
len Amount of data to send
dest BT address of the destination
psm Identifies the service the data shall be delivered to on the receiving side
bc_flag Determines if the packet should be broadcasted or not
ttl Maximal time to live for the packet - pass TTL_INFINITE for inifinite time to live
Returns:
0 or possible errors:
Example 1:
u_char data[12];
strcpy(data, "hello world");
mhop_cl_send_pkt(data, 12, <target_addr>, <target_psm>, MHOP_CL_BROADCAST, 5);
sends "hello world" to the device with address 'target_addr'. The packet will be broadcasted, but only the device with BT address <target_addr> will deliver the packet to the service identified with the specified PSM 'target_psm'. The packet will be forwarded at most five times.

Example 2:

u_char data[19];
strcpy(data, "fifa world cup 2006");
mhop_cl_send_pkt(data, 20, <target_addr>, <target_psm>, MHOP_CL_UNICAST, MHOP_CL_TTL_INFINITE);
sends the string "fifa world cup 2006" to the device with address 'target_addr'. The packet is forwarded as long as intermediate hops know how to forward packets to the specified device.

Example 3:

u_char data[12];
strcpy(data, "hello world");
mhop_cl_send_pkt(data, 12, bt_addr_null, <target_psm>, MHOP_CL_BROADCAST, MHOP_CL_TTL_INFINITE);
sends the string "hello world" to _all_ devices in the network. The string "hello world" is passed to the service identified with psm 'target_psm' on _all_ devices in the network.
Examples:
mhop_blink/mhop_blink.c.

long mhop_cl_send_src_del_pkt ( bt_addr_t  addr,
u_char  ttl 
)

broadcasts a source deletion packet

Sends an packet indicating that the device with addr addr should be cleared from the forwarding table.

Note: the packet is broadcasted, that is every node in the network deletes the device with addr addr from the forwarding table.

Parameters:
addr BT address of the device to be deleted
ttl Maximal time to live for this source deletion packet


Generated on Wed Apr 29 11:12:29 2009 for BTnut System Software by doxygen 1.5.1