btnut/btnode/include/bt/l2cap_cl.h File Reference


Detailed Description

Connection-less data protocol API.

Author:
Kevin Martin <kevmarti@tik.ee.ethz.ch>
Date:
2006/03/23
Provides functions to send connection-less data to directely connected neighbors.

To receive l2cap connection-less data, an application has to register its service routine at the protocol/service multiplexor, together with a "PSM" - a unique number identifying the service. Connection-less data can then be sent to a specific service by sending it to the corresponding "PSM". Refer to l2cap_cl_send and bt_psm.h for further details.

See also:
bt_psm.h
bt_l2cap.h
mhop_cl.h
Note: This is not an implementation of the l2cap connection-less protocol as defined in the Bluetooth specification, although the packet format used is equivalent to the definition of l2cap connection-less packets (see note below).

#include <sys/types.h>
#include <bt/bt_defs.h>
#include <bt/bt_hci_defs.h>
#include <bt/bt_acl_pkt_buf.h>
#include <bt/bt_psm.h>

Defines

#define L2CAP_CL_PSM_FIELD_SIZE   2
 Size of the PSM field.
Errors
#define L2CAP_CL_ERR_PAYLOAD_OVERFLOW   -1

Functions

u_long l2cap_cl_get_arrival_time (bt_acl_pkt_buf *pkt_buf)
 Returns the arrival time of the packet passed.
u_charl2cap_cl_get_data_ptr (struct bt_hci_pkt_acl *pkt)
 Returns indexed drop counter. Increments indexed drop counter. Increments also the above drop counter. Returns a pointer to the payload of a received l2cap connection-less packet.
u_short l2cap_cl_max_payload (void)
 Returns the max payload size of a connection-less l2cap packet.
Sending L2CAP connection-less Data
long l2cap_cl_acquire_write_lock (bt_hci_con_handle_t hdl, u_short psm, u_short len)
 Acquires lock on bt-uart for sending l2cap connection-less data.
long l2cap_cl_lowlevel_write (u_char *data, u_short len)
 Writes connection-less data to the bluetooth uart.
void l2cap_cl_release_write_lock (void)
 Releases unique access for sending l2cap connection-less data.
long l2cap_cl_send (u_char *data, u_short len, bt_hci_con_handle_t hdl, u_short psm)
 Sends a connection-less l2cap data packet.
Packet statistics
u_long l2cap_cl_get_dropped_traffic (void)
 Returns the number of dropped packets.
u_long l2cap_cl_get_incoming_traffic (void)
 Returns the number of received packets.
u_long l2cap_cl_get_outgoing_traffic (void)
 Returns the number of sent packets.
void l2cap_cl_increment_drop_counter (void)
 Increments drop counter.
Initialization
void l2cap_cl_init (struct btstack *bt_stack, bt_psm_t *mux)
 Initializes the connectionless l2cap layer.
L2CAP callback registration
void l2cap_cl_register_acl_cb (struct btstack *bt_stack, HCI_ACL_CB, void *arg)
 To register a callback funtion handling L2CAP data packets.


Define Documentation

#define L2CAP_CL_ERR_PAYLOAD_OVERFLOW   -1

The payload of the l2cap connection-less data packet to send is too large


Function Documentation

long l2cap_cl_acquire_write_lock ( bt_hci_con_handle_t  hdl,
u_short  psm,
u_short  len 
)

Acquires lock on bt-uart for sending l2cap connection-less data.

Locks the bluetooth uart for writing l2cap connection-less data. The lock is not released until l2cap_cl_release_write_lock has been called.

Note: Applications typically do not call this function, but make use of l2cap_cl_send instead.

Parameters:
hdl Connection handle of the connected neighbor device the data shall be sent to.
psm PSM the data will be sent to on the receiving side.
len Amount of data to be sent.
Returns:
0 or possible errors:
See also:
l2cap_cl_lowlevel_write
l2cap_cl_release_write_lock

u_char* l2cap_cl_get_data_ptr ( struct bt_hci_pkt_acl pkt  )  [inline]

Returns indexed drop counter. Increments indexed drop counter. Increments also the above drop counter. Returns a pointer to the payload of a received l2cap connection-less packet.

Parameters:
pkt Pointer to the received packet
Returns:
pointer to the payload

void l2cap_cl_init ( struct btstack bt_stack,
bt_psm_t mux 
)

Initializes the connectionless l2cap layer.

Note: The bt-stack, the ACL layer, as well as the protocol/service multiplexor have to be initialized before calling this function. Thus, make shure that:

Parameters:
bt_stack Pointer to the bt-stack to use
mux Pointer to the protocol/service multiplexor to use
Examples:
bt-lego/bt-lego.c, and mhop_blink/mhop_blink.c.

long l2cap_cl_lowlevel_write ( u_char data,
u_short  len 
) [inline]

Writes connection-less data to the bluetooth uart.

Writes l2cap connection-less data directely to the bt uart iff unique write access has been aquired before (i.e. l2cap_cl_acquire_write_lock has been called).

Note: Applications typically do not call this function, but make use of l2cap_cl_send instead.

Parameters:
data Data to write
len Size of the data to write
See also:
l2cap_cl_acquire_write_lock
l2cap_cl_release_write_lock

void l2cap_cl_register_acl_cb ( struct btstack bt_stack,
HCI_ACL_CB  ,
void *  arg 
)

To register a callback funtion handling L2CAP data packets.

Call this function to register a higher layer service (i.e. l2cap) which handles the data that is not handled by the l2cap connection-less layer (i.e. l2cap packets that are not sent to the connection-less channel).

Note: l2cap_cl and l2cap cannot run together at the moment!

void l2cap_cl_release_write_lock ( void   )  [inline]

Releases unique access for sending l2cap connection-less data.

Releases the writing lock on the bluetooth controller triggered by l2cap_cl_acquire_write_lock.

Note: Applications typically do not call this function, but make use of l2cap_cl_send instead.

See also:
l2cap_cl_acquire_write_lock
l2cap_cl_lowlevel_write

long l2cap_cl_send ( u_char data,
u_short  len,
bt_hci_con_handle_t  hdl,
u_short  psm 
)

Sends a connection-less l2cap data packet.

Sends connection-less l2cap data of length len over connection handle con_handle to the psm psm.

Note: The maximal amount of data that can be sent is obtained by calling l2cap_cl_max_payload.

Parameters:
data pointer to the data to be sent
len amount of data to be sent
hdl connection handle the data shall be sent to
psm PSM the data shall be sent to (the PSM identifies the service the data will be delivered to on the receiving side (see bt_psm_service_register).
Returns:
0 or possible errors:
Example:
u_char data[12];
strcpy(data, "hello world");
l2cap_cl_send(data, <con_handle>, <psm>, 12);

See also:
bt_psm.h


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