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


Detailed Description

Implements L2CAP communicarion layer.

Author:
Ole Reinhardt <ole.reinhardt@embedded-it.de>
Date:
25.01.2005
See Bluetooth 1.1 specification for better understanding of l2cap.

#include <sys/types.h>
#include <bt/bt_defs.h>

Data Structures

struct  bt_l2cap_acl_buffer_entry
 Buffer entry for internal acl packet buffering. More...
struct  bt_l2cap_acl_pkt
 Represents one l2cap packet including the acl header. More...
struct  bt_l2cap_bb_connection
struct  bt_l2cap_channel
 This struct represents one l2cap channel. More...
struct  bt_l2cap_pkt_buffer_entry
 Buffer entry for internal l2cap packet buffering. More...
struct  bt_l2cap_service
 This struct represents one service. More...
struct  bt_l2cap_signal
 This struct contains the header fields of a l2cap signaling packet. More...
struct  bt_l2cap_signal_buffer
 Buffer entry for internal l2cap signal buffering. More...
struct  bt_l2cap_stack
 Represents one entity of the l2cap layer itself. More...
struct  l2cap_echo_cmd

Callback detail

#define BT_L2CAP_CON_ACTIVE   0x02
#define BT_L2CAP_CON_CB   void (*con_cb) (u_char type, u_char detail, u_char service_nr, u_short channel_id, void *arg)
#define BT_L2CAP_CON_PASSIVE   0x03
#define BT_L2CAP_DISCON_LINK_LOST   0x04
#define BT_L2CAP_RCV_CB   void (*rcv_cb) (struct bt_l2cap_acl_pkt *pkt, u_char service_nr, u_short channel_id, void *arg)
#define BT_L2CAP_UNKNOWN   0x01
l2cap_echo_cmd echo_cmd
bt_l2cap_stackl2cap_stack
bt_l2cap_signal packed
bt_l2cap_acl_pkt packed
bt_l2cap_channel_bt_l2cap_get_channel_from_channel_id (u_short channel_id)
u_char _bt_l2cap_get_new_sigid (struct bt_l2cap_bb_connection *bb_con)
bt_l2cap_service_bt_l2cap_get_service_from_channel_id (u_short channel_id)
bt_l2cap_bb_connection_bt_l2cap_handle2baseband (bt_hci_con_handle_t con_handle)
u_char bt_l2cap_clear_service (u_char service_nr)
 This command clears a previosly registered service.
void bt_l2cap_complete_pkt (struct bt_l2cap_acl_pkt *pkt)
 Informs the baseband that an packet can be freed (flow control).
u_char bt_l2cap_connect (u_char service_nr, bt_addr_t bt_addr, u_char page_scan_rep_mode, u_short clock_offset, u_short psm, u_short *channel_id)
 This command will open a channel to a remote device.
u_char bt_l2cap_disconnect (u_short channel_id)
 This command will close a previously opened connection.
u_char bt_l2cap_get_hci_connection_handle (u_short channel_id, bt_hci_con_handle_t *con_handle)
 Queries the baseband connection handle an established channel.
u_char bt_l2cap_get_incomming_mtu (u_short channel_id, u_short *mtu)
 Queries the incomming mtu of an established channel.
u_char bt_l2cap_get_local_cid (u_short channel_id, u_short *cid)
 Queries the local cid of an established channel.
u_char bt_l2cap_get_outgoing_mtu (u_short channel_id, u_short *mtu)
 Queries the outgoing mtu of an established channel.
u_char bt_l2cap_get_remote_cid (u_short channel_id, u_short *cid)
 Queries the remote cid of an established channel.
bt_l2cap_stackbt_l2cap_init (struct btstack *bt_stack, u_char nr_buffer, u_char max_channel, u_short pkt_types)
u_char bt_l2cap_is_ch_open (u_short channel_id)
 Checks if a channel_id is valid (the channel is opened).
u_char bt_l2cap_l2ping (bt_addr_t bt_addr, u_char *payload, u_short len, u_long *time)
 Send a l2cap echo request to a specific device and queries the return time of the packet.
u_char bt_l2cap_register_service (u_short psm, u_char nr_buffer, u_short min_mtu, u_short max_mtu, BT_L2CAP_CON_CB, BT_L2CAP_RCV_CB, void *cb_arg)
 This command registers a service (the next higher layer).
u_long bt_l2cap_send (u_short channel_id, struct bt_l2cap_acl_pkt *pkt, u_short len)
 Sends data over a connected channel.

Defines

Header length defintions
#define BT_L2CAP_ACL_PKT_HDR_LEN   (5 + HCI_ACL_DATA_PKT_HDR)
#define BT_L2CAP_HEADER_LEN   4
#define BT_L2CAP_SIG_HEADER_LEN   4
ACL packet sizes for differen acl pkt types
#define BT_L2CAP_ACL_SIZE_DH1   28
#define BT_L2CAP_ACL_SIZE_DH3   185
#define BT_L2CAP_ACL_SIZE_DH5   341
#define BT_L2CAP_ACL_SIZE_DM1   18
#define BT_L2CAP_ACL_SIZE_DM3   123
#define BT_L2CAP_ACL_SIZE_DM5   226
Connection status infos
#define BT_L2CAP_AUTHENTICATION_PENDING   0x0001
#define BT_L2CAP_AUTHORIZATION_PENDING   0x0002
#define BT_L2CAP_NO_FURTHER_INFO   0x0000
Channel state codes (internal state machine)
#define BT_L2CAP_CH_CLOSED   0x01
#define BT_L2CAP_CH_CONFIG   0x04
#define BT_L2CAP_CH_NOT_ASSIGNED   0x00
#define BT_L2CAP_CH_OPEN   0x06
#define BT_L2CAP_CH_W4_L2CAP_CONNECT   0x03
#define BT_L2CAP_CH_W4_L2CAP_CONNECT_RSP   0x02
#define BT_L2CAP_CH_W4_L2CAP_DISCONNECT_RSP   0x07
Some defines for error or not initialized conditions
#define BT_L2CAP_CHANNEL_INFO_SIZE   (sizeof(struct bt_l2cap_acl_buffer_entry *))
#define BT_L2CAP_CHNR_INVALID   0xFF
#define BT_L2CAP_HANDLE_INVALID   0x00
#define BT_L2CAP_MAX_CHANNELS   0xFE
#define BT_L2CAP_MAX_SERVICES   16
#define BT_L2CAP_SERVICENR_INVALID   0xFF
Predefined channel identifiers (CIDs)
#define BT_L2CAP_CID_CONNECTIONLESS   0x0002
#define BT_L2CAP_CID_MAX   0xFFFF
#define BT_L2CAP_CID_SERVICES   0xFF00
#define BT_L2CAP_CID_SIG   0x0001
#define BT_L2CAP_CID_USER   0x0040
Connection request results (SIG_CON)
#define BT_L2CAP_CON_PENDING   0x0001
#define BT_L2CAP_CON_PSM_NOT_SUPPORTED   0x0002
#define BT_L2CAP_CON_REJ_NO_RESSOURCE   0x0004
#define BT_L2CAP_CON_SECURITY_BLOCK   0x0003
#define BT_L2CAP_CON_SUCCESS   0x0000
Configuration request options (SIG_CONF)
#define BT_L2CAP_CONF_OPT_FLUSH   0x02
#define BT_L2CAP_CONF_OPT_MTU   0x01
#define BT_L2CAP_CONF_OPT_NONE   0x00
#define BT_L2CAP_CONF_OPT_QOS   0x03
#define BT_L2CAP_CONF_OPT_RTR_FLOW   0x04
Configuration request results (SIG_CONF)
#define BT_L2CAP_CONF_REJECT   0x0002
#define BT_L2CAP_CONF_SUCCESS   0x0000
#define BT_L2CAP_CONF_UNACCAPTABLE   0x0001
#define BT_L2CAP_CONF_UNKNOWN_OPTIONS   0x0003
Callback types
#define BT_L2CAP_CONNECT   0x01
#define BT_L2CAP_DISCONNECT   0x02
Error codes
#define BT_L2CAP_ERR_BB_CON_FAILED   0x02
#define BT_L2CAP_ERR_CH_CONFIG   0x15
#define BT_L2CAP_ERR_CH_NOT_OPEN   0x06
#define BT_L2CAP_ERR_CMD_PENDING   0x07
#define BT_L2CAP_ERR_CON_PENDING   0x12
#define BT_L2CAP_ERR_DATASIZE   0x0A
#define BT_L2CAP_ERR_IN_USE   0x08
#define BT_L2CAP_ERR_INVALID_CID   0x05
#define BT_L2CAP_ERR_INVALID_HANDLE   0x09
#define BT_L2CAP_ERR_INVALID_PSM   0x01
#define BT_L2CAP_ERR_NO_RESSOURCE   0x03
#define BT_L2CAP_ERR_OUT_OF_MEMORY   0x0B
#define BT_L2CAP_ERR_PAYLOAD_LEN   0x11
#define BT_L2CAP_ERR_PING_PENDING   0x10
#define BT_L2CAP_ERR_PSM_NOT_SUPPORTED   0x13
#define BT_L2CAP_ERR_SECURITY_BLOCK   0x14
#define BT_L2CAP_ERR_SUCCESS   0x00
#define BT_L2CAP_ERR_TIMEOUT   0x04
Flags for channel status
#define BT_L2CAP_FLAG_CMD_MASK   0x0F
#define BT_L2CAP_FLAG_CON_RSP   0x08
#define BT_L2CAP_FLAG_CONF_REQ   0x02
#define BT_L2CAP_FLAG_CONF_RSP   0x04
#define BT_L2CAP_FLAG_DISC_RSP   0x01
#define BT_L2CAP_FLAG_INITIATOR   0x80
#define BT_L2CAP_FLAG_WAS_CON   0x20
Types of information packets (SIG_INFO)
#define BT_L2CAP_INFO_CONLESS_MTU   0x0001
#define BT_L2CAP_INFO_EXT_FEATURES   0x0002
#define BT_L2CAP_INFO_NOT_SUPPORTED   0x0001
#define BT_L2CAP_INFO_SUCCESS   0x0000
MTU definitions
#define BT_L2CAP_MIN_MTU   48
#define BT_L2CAP_MTU_DEFAULT   672
Flow control and retransmission modes (SIG_CONF)
#define BT_L2CAP_MODE_BASIC   0x00
#define BT_L2CAP_MODE_FLOW   0x02
#define BT_L2CAP_MODE_RTR   0x01
Some known predifined PSMs
#define BT_L2CAP_PSM_BNEP   0x000F
#define BT_L2CAP_PSM_INVALID   0x0000
#define BT_L2CAP_PSM_RFCOMM   0x0003
Quality of service options (SIG_CONF)
#define BT_L2CAP_QOS_BEST_EFFORT   0x01
#define BT_L2CAP_QOS_GUARANTEED   0x02
#define BT_L2CAP_QOS_NO_TRAFFIC   0x00
Reject reasons of a signalling command
#define BT_L2CAP_REJ_CMD_NOT_UNDERSTOOD   0x0000
#define BT_L2CAP_REJ_INVALID_CID   0x0002
#define BT_L2CAP_REJ_MTU_EXCEEDED   0x0001
Signalling codes for l2cap signaling packets
#define BT_L2CAP_SIG_CMD_REJ   0x01
#define BT_L2CAP_SIG_CON_REQ   0x02
#define BT_L2CAP_SIG_CON_RSP   0x03
#define BT_L2CAP_SIG_CONF_REQ   0x04
#define BT_L2CAP_SIG_CONF_RSP   0x05
#define BT_L2CAP_SIG_DISC_REQ   0x06
#define BT_L2CAP_SIG_DISC_RSP   0x07
#define BT_L2CAP_SIG_ECHO_REQ   0x08
#define BT_L2CAP_SIG_ECHO_RSP   0x09
#define BT_L2CAP_SIG_INFO_REQ   0x0a
#define BT_L2CAP_SIG_INFO_RSP   0x0b
Signalling timeouts in ms
#define BT_L2CAP_SIGNAL_TIMEOUT   5000
#define BT_L2CAP_SIGNAL_TIMEOUT_PENDING   60000


Define Documentation

#define BT_L2CAP_ACL_PKT_HDR_LEN   (5 + HCI_ACL_DATA_PKT_HDR)

Header length of an acl packet

#define BT_L2CAP_CON_CB   void (*con_cb) (u_char type, u_char detail, u_char service_nr, u_short channel_id, void *arg)

Connection callback definition

This callback will be called whenever a l2cap connection is established or closed on a specific PSM. This is specified by the service registration routine.

Parameters:
type Type of callback: BT_L2CAP_CONNECT or BT_L2CAP_DISCONNECT
detail Information about the callbacks reason. Possible values: BT_L2CAP_UNKNOWN BT_L2CAP_CON_ACTIVE BT_L2CAP_CON_PASSIVE BT_L2CAP_DISCON_LINK_LOST
service_nr Number of the service this callback is assigned to
channel_id Channel ID of the l2cap channel this callback is assigned to
arg Pointer to the callback argument. (see register service)

#define BT_L2CAP_HEADER_LEN   4

Header length of a l2cap packet

#define BT_L2CAP_MAX_CHANNELS   0xFE

Defines maximum nr of services the l2cap layer can handle. A service is the logical endpoint that will receive and handle the data fom the l2cap connection. In other words the next higher layer (i.e. rfcomm)

Not more than 5 bits as they are used to encode the service nr in the unique l2cap id

#define BT_L2CAP_MTU_DEFAULT   672

Maximum transmission unit default values

Examples:
l2cap-cmd/l2cap-cmd.c, and rfcomm-cmd/rfcomm-cmd.c.

#define BT_L2CAP_RCV_CB   void (*rcv_cb) (struct bt_l2cap_acl_pkt *pkt, u_char service_nr, u_short channel_id, void *arg)

Receive callback definition

This callback will be called whenever any user data is received by the l2cap layer on a specific PSM. This is specified by the service registration routine.

Parameters:
pkt Pointer to the reveiced acl packet
service_nr Number of the service this callback is assigned to
channel_id Channel ID of the l2cap channel this callback is assigned to
arg Pointer to the callback argument. (see register service)

#define BT_L2CAP_SIG_HEADER_LEN   4

Header length of a l2cap signaling packet


Function Documentation

u_char bt_l2cap_clear_service ( u_char  service_nr  ) 

This command clears a previosly registered service.

After calling this command, the service is no longer registered. The service may not be in use.

Parameters:
service_nr Number of the service to be cleared
Returns:
BT_L2CAP_ERR_SUCCESS or one of the following errors:
  • BT_L2CAP_ERR_IN_USE

void bt_l2cap_complete_pkt ( struct bt_l2cap_acl_pkt pkt  ) 

Informs the baseband that an packet can be freed (flow control).

This function is used for flow control reasons. Every packet received by a service needs to be completed with this function. This function will inform the baseband that the reserved buffer can be cleared and will also clear l2cap internal buffers. If the packets won't be completed the baseband will stop receiving any more packets after The internal buffer runs full.

Parameters:
pkt l2cap packet to be completed

u_char bt_l2cap_connect ( u_char  service_nr,
bt_addr_t  bt_addr,
u_char  page_scan_rep_mode,
u_short  clock_offset,
u_short  psm,
u_short channel_id 
)

This command will open a channel to a remote device.

Opening a channel will connect a waiting service with the specified PSM of the remote device. If no baseband connection is yet established, a baseband connection will be established first. After successfull connection the data can be transferred.

Uppler layers will be informed by a connection callback

Parameters:
service_nr Number of the service to be connected to the remote device
bt_addr Bluetooth address of the remote device
page_scan_rep_mode Page scan mode (found during inquiry) (pass 0 if unknown)
clock_offset Offset to this device (found during inquiry). pass 0 if unknown
psm PSM of the connection endpoint
channel_id of new connection is stored here, if not null
Returns:
BT_L2CAP_ERR_SUCCESS or one of the following errors:
  • BT_L2CAP_ERR_INVALID_HANDLE
  • BT_L2CAP_ERR_NO_RESSOURCE
  • BT_L2CAP_ERR_INVALID_PSM
  • BT_L2CAP_ERR_BB_CON_FAILED
  • BT_L2CAP_ERR_TIMEOUT

u_char bt_l2cap_disconnect ( u_short  channel_id  ) 

This command will close a previously opened connection.

After closing the channel no more data can be transfered. Uppler layers will be informed by a connection callback

Parameters:
channel_id ID of the channel to be closed. Will be passed by the connection callback.
Returns:
BT_L2CAP_ERR_SUCCESS or one of the following errors:
  • BT_L2CAP_ERR_INVALID_HANDLE
  • BT_L2CAP_ERR_INVALID_CID
  • BT_L2CAP_ERR_CH_NOT_OPEN
  • BT_L2CAP_ERR_CMD_PENDING
  • BT_L2CAP_ERR_TIMEOUT

u_char bt_l2cap_get_hci_connection_handle ( u_short  channel_id,
bt_hci_con_handle_t con_handle 
)

Queries the baseband connection handle an established channel.

Parameters:
channel_id ID of the channel
con_handle Baseband connection handle of the channel (call by reference)
Returns:
BT_L2CAP_ERR_SUCCESS or one of the following errors:
  • BT_L2CAP_ERR_INVALID_HANDLE

u_char bt_l2cap_get_incomming_mtu ( u_short  channel_id,
u_short mtu 
)

Queries the incomming mtu of an established channel.

Parameters:
channel_id ID of the channel
mtu Incomming MTU of the channel (call by reference)
Returns:
BT_L2CAP_ERR_SUCCESS or one of the following errors:
  • BT_L2CAP_ERR_INVALID_HANDLE

u_char bt_l2cap_get_local_cid ( u_short  channel_id,
u_short cid 
)

Queries the local cid of an established channel.

Parameters:
channel_id ID of the channel
cid Local CID of the channel (call by reference)
Returns:
BT_L2CAP_ERR_SUCCESS or one of the following errors:
  • BT_L2CAP_ERR_INVALID_HANDLE

u_char bt_l2cap_get_outgoing_mtu ( u_short  channel_id,
u_short mtu 
)

Queries the outgoing mtu of an established channel.

Parameters:
channel_id ID of the channel
mtu Outgoing MTU of the channel (call by reference)
Returns:
BT_L2CAP_ERR_SUCCESS or one of the following errors:
  • BT_L2CAP_ERR_INVALID_HANDLE

u_char bt_l2cap_get_remote_cid ( u_short  channel_id,
u_short cid 
)

Queries the remote cid of an established channel.

Parameters:
channel_id ID of the channel
cid Remote CID of the channel (call by reference)
Returns:
BT_L2CAP_ERR_SUCCESS or one of the following errors:
  • BT_L2CAP_ERR_INVALID_HANDLE

struct bt_l2cap_stack* bt_l2cap_init ( struct btstack bt_stack,
u_char  nr_buffer,
u_char  max_channel,
u_short  pkt_types 
)

Initializes the l2cap stack.

Parameters:
bt_stack Pointer to btstack
nr_buffer Number of receive-buffer for l2cap packets
max_channel Maximum number of channels that can be used over one bb connection
pkt_types Bitmask of the acl packet types allowed. Example: BT_HCI_PACKET_TYPE_DM1 | BT_HCI_PACKET_TYPE_DH1 | BT_HCI_PACKET_TYPE_DM3 | BT_HCI_PACKET_TYPE_DH3
Returns:
Pointer to the l2cap stack entity created by this function.
Examples:
bt-remoteprog/demo-rprog.c, l2cap-cmd/l2cap-cmd.c, and rfcomm-cmd/rfcomm-cmd.c.

u_char bt_l2cap_is_ch_open ( u_short  channel_id  ) 

Checks if a channel_id is valid (the channel is opened).

Returns:
TRUE if assigned, else false

u_char bt_l2cap_l2ping ( bt_addr_t  bt_addr,
u_char payload,
u_short  len,
u_long time 
)

Send a l2cap echo request to a specific device and queries the return time of the packet.

Parameters:
bt_addr Bluetooth address of the remote device
payload Payload to be send with the echo request
len Length of the payload (my not be larger than one acl packet)
time returns the return time of the packet (call by reference)
Returns:
BT_L2CAP_ERR_SUCCESS or one of the following errors:
  • BT_L2CAP_ERR_PAYLOAD_LEN
  • BT_L2CAP_ERR_PING_PENDING
  • BT_L2CAP_ERR_BB_CON_FAILED
  • BT_L2CAP_ERR_TIMEOUT

u_char bt_l2cap_register_service ( u_short  psm,
u_char  nr_buffer,
u_short  min_mtu,
u_short  max_mtu,
BT_L2CAP_CON_CB  ,
BT_L2CAP_RCV_CB  ,
void *  cb_arg 
)

This command registers a service (the next higher layer).

A service is the logical endpoint that will receive and handle the data fom the l2cap connection. In other words the next higher layer (i.e. rfcomm)

Changed MTU handling: Now we only have to define a minimum MTU the opposite device has to accept for this service. Our maximum MTU is given as the stacks max_mtu

Parameters:
psm The PSM the service will use
nr_buffer Number of l2cap packet buffers that should be reserved for this service Note: The service must be able to handle nr_buffer + number of acl buffers given on l2cap initialisation l2cap packets before one packet is freed. So always keep in mind to reserve enough buffers in your service. See bt_rfcomm for example
min_mtu Minimum MTU value that the opposite device has to accept
max_mtu Maximum MTU value our service will use
BT_L2CAP_CON_CB Connection callback. Will be called if the datalink connection to this service is established or closed.
BT_L2CAP_RCV_CB Receive callback. Will be called whenever data is received on an established datalink
cb_arg Pointer to a optional callback argument
Returns:
Number of the service or BT_L2CAP_SERVICENR_INVALID on an errors

u_long bt_l2cap_send ( u_short  channel_id,
struct bt_l2cap_acl_pkt pkt,
u_short  len 
)

Sends data over a connected channel.

Parameters:
channel_id ID of the channel
pkt l2cap packet to be send. Fillin only the payload, header will be added by the function.
len Length of the payload (may not be larger than the outgoing mtu of the channel
Returns:
BT_L2CAP_ERR_SUCCESS or one of the following errors:
  • BT_L2CAP_ERR_INVALID_HANDLE
  • BT_L2CAP_ERR_DATASIZE
  • BT_L2CAP_ERR_INVALID_CID
  • BT_L2CAP_ERR_CH_NOT_OPEN
  • BT_L2CAP_ERR_CMD_PENDING
  • One of the errors from bt_hci_send_acl_pkt


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