Logical Link Control and Adaptation Protocol (L2CAP)

API Reference

---

• Common
• BR/EDR
• BLE

group l2cap

Logical Link Control and Adaptation Layer Protocol, referred to as L2CAP, provides connection oriented and connectionless data services to upper layer protocols with protocol multiplexing capability and segmentation and reassembly operation.

L2CAP connection result codes

L2CAP connection result codes.

L2CAP_CONN_OK

Connection OK.

L2CAP_CONN_PENDING

Connection Pending.

L2CAP_CONN_NO_PSM

Connection NO PSM.

L2CAP_CONN_SECURITY_BLOCK

Connection Security Block.

L2CAP_CONN_NO_RESOURCES

Connection NO Resource.

L2CAP_CONN_BAD_CTLR_ID

Bad Controller ID.

note

AMP related

L2CAP_BLE_CONN_BAD_AUTHENT

BLE Connection Bad Authentication.

L2CAP_BLE_CONN_BAD_AUTHORIZ

BLE Connection Bad Autherization.

L2CAP_BLE_CONN_BAD_KEY_SIZE

BLE Connection Bad key size.

L2CAP_BLE_CONN_BAD_ENCRYPT

BLE Connection Bad Encryption.

L2CAP ECRB Result Code

L2CAP ECRB Result Code

L2CAP_ECRB_ALL_CONNS_SUCCESSFUL

All Connections Successful.

L2CAP_ECRB_ALL_CONNS_REFUSED

All Connections Refused.

L2CAP_ECRB_SOME_CONNS_REFUSED

Some Connections Refused.

L2CAP_ECRB_INSUFF_AUTHENTICATION

Insufficient Authentication.

L2CAP_ECRB_INSUFF_AUTHORIZATION

Insufficient Autherization.

L2CAP_ECRB_INSUFF_KEY_SIZE

Insufficient Key size.

L2CAP_ECRB_INSUFF_ENCRYPTION

Insufficient Encryption.

L2CAP_ECRB_INVALID_SOURCE_CID

Invalid Source CID.

L2CAP_ECRB_SOURCE_CID_IN_USE

Source CID in Used.

L2CAP_ECRB_UNACCEPTABLE_PARAMS

Unacceptable Params.

L2CAP_ECRB_INVALID_PARAMS

Invalid Params.

L2CAP_ECRB_RECONFIG_SUCCESSFUL

Reconfiguration Successful.

L2CAP_ECRB_RECONFIG_FAIL_BAD_MTU

Reconfiguration fail : Bad MTU.

L2CAP_ECRB_RECONFIG_FAIL_BAD_MPS

Reconfiguration fail : Bad MPS.

L2CAP_ECRB_RECONFIG_FAIL_BAD_DCID

Reconfiguration fail : Bad DCID.

L2CAP_ECRB_RECONFIG_FAIL_OTHER

Reconfiguration fail : Other Reason.

L2CAP_ECRB_NOT_SUPPORTED_BY_PEER

Not Supported by Peer.

L2CAP ping result

Ping result codes.

L2CAP_PING_RESULT_OK

Ping reply received OK.

L2CAP_PING_RESULT_NO_LINK

Link could not be setup.

L2CAP_PING_RESULT_NO_RESPONSE

Remote L2CAP did not reply.

L2CAP data write result

Result codes for wiced_bt_l2cap_data_write()

L2CAP_DATAWRITE_FAILED

If data not accepted and error.

L2CAP_DATAWRITE_SUCCESS

If data accepted.

L2CAP_DATAWRITE_CONGESTED

if data accepted and the channel is congested

L2CAP data write flags

Flushable/Non Flushable flags parameter used in a call wiced_bt_l2cap_data_write()

L2CAP_FLUSHABLE_MASK

L2CAP Flushable mask.

L2CAP_NON_FLUSHABLE_PACKET

Non Flushable flag.

L2CAP_FLUSHABLE_PACKET

Flushable flag.

L2CAP PSM

Validity check for PSM. PSM values must be odd. Also, all PSM values must be assigned such that the least significant bit of the most sigificant octet equals zero.

L2C_INVALID_PSM(psm)

Returns true on invalid PSM.

L2C_IS_VALID_PSM(psm)

Returns true on valid PSM.

L2CAP channel configuration

L2CAP channel configured field bitmap. Used for wiced_bt_l2cap_ch_cfg_bits_t

L2CAP_CH_CFG_MASK_MTU

MTU channel configuration bit mask.

L2CAP_CH_CFG_MASK_QOS

QOS channel configuration bit mask.

L2CAP_CH_CFG_MASK_FLUSH_TO

Flush to channel configuration bit mask.

L2CAP_CH_CFG_MASK_FCR

FCR channel configuration bit mask.

L2CAP_CH_CFG_MASK_FCS

FCS channel configuration bit mask.

L2CAP_CH_CFG_MASK_EXT_FLOW_SPEC

Extended flow specification channel configuration bit mask.

L2CAP FCR Mode

L2CAP FCR mode configuring options and allowed modes bit mask. From below, first 3 used as a field wiced_bt_l2cap_fcr_options_t::mode and reamining used as a bit mask field wiced_bt_l2cap_ertm_information_t::allowed_modes

L2CAP_FCR_BASIC_MODE

Basic mode (no FCR)

L2CAP_FCR_ERTM_MODE

ERTM mode.

L2CAP_FCR_STREAM_MODE

Streaming mode.

L2CAP_FCR_CHAN_OPT_BASIC

Basic mode (no FCR) bit mask.

L2CAP_FCR_CHAN_OPT_ERTM

ERTM mode bit mask.

L2CAP_FCR_CHAN_OPT_STREAM

Streaming mode bit mask.

L2CAP_FCR_CHAN_OPT_ALL_MASK

Mask for all modes Basic, ERTM and Streaming.

L2CAP flush channels

L2CAP flush channel and num_to_flush parameter used in a call wiced_bt_l2cap_flush_channel()

L2CAP_FLUSH_CHANNELS_ALL

To flush all queued buffers.

L2CAP_FLUSH_CHANNELS_GET

To get queued buffers to flush.

L2CAP role

L2CAP role and new_role parameter used in a call wiced_bt_l2cap_set_desire_role()

note

L2CAP_ROLE_SCATTERNET_ALLOWED bit is used to prevent l2CAP to Automatically perform role switch (for both Incoming and outgoing) ACL connections.

L2CAP_ROLE_PERIPHERAL

L2CAP Peripheral role.

L2CAP_ROLE_CENTRAL

L2CAP Central role.

L2CAP_ROLE_ALLOW_SWITCH

set this bit to allow switch at create conn

L2CAP_ROLE_DISALLOW_SWITCH

set this bit to disallow switch at create conn

L2CAP_ROLE_CHECK_SWITCH

To check the switch to allow or disallow.

L2CAP_ROLE_SCATTERNET_ALLOWED

set this bit to allow scatternet

L2CAP ACL Priority Value

Values for priority parameter to wiced_bt_l2cap_set_acl_priority() and wiced_bt_l2cap_set_acl_priority_ext().

L2CAP_PRIORITY_NORMAL

Set ACL priority as normal.

L2CAP_PRIORITY_HIGH

Set ACL priority as high.

L2CAP ACL Priority Direction

Values for direction parameter to wiced_bt_l2cap_set_acl_priority_ext()

L2CAP_DIRECTION_IGNORE

Set ACL priority direction as ignore.

L2CAP_DIRECTION_DATA_SOURCE

Set ACL priority direction as source.

L2CAP_DIRECTION_DATA_SINK

Set ACL priority direction as sink.

L2CAP transmission channel priority

L2CAP channel transmission priority. Used for wiced_bt_l2cap_chnl_priority_t

L2CAP_CHNL_PRIORITY_HIGH

Transmission priority as high for a channel (FCR Mode)

L2CAP_CHNL_PRIORITY_MEDIUM

Transmission priority as medium for a channel (FCR Mode)

L2CAP_CHNL_PRIORITY_LOW

Transmission priority as low for a channel (FCR Mode)

L2CAP LE PSM

Validity check for LE_PSM. Fixed LE_PSMs are in the range 0x0001 - 0x007F. Dynamic LE_PSM are in the range 0x0080 - 0x00FF. The values 0x0000 and 0x0100 - 0xFFFF are reserved.

MINIMIUM_DYNAMIC_LE_PSM

First application dynamic PSM allowed.

MAXIMUM_LE_PSM

LE PSM range limit.

L2C_BLE_INVALID_PSM(le_psm)

Returns true on invalid LE PSM.

L2C_BLE_IS_VALID_PSM(le_psm)

Returns true on valid LE PSM.

Defines

L2CAP_ECRB_MAX_CHANNELS_PER_CMD

ECRB Max Channels per Command.

L2CAP_ECRB_MIN_MTU

ECRB Min MTU.

L2CAP_ECRB_MIN_MPS

ECRB Min MPS.

L2CAP_MINIMUM_OFFSET

Minimum offset that L2CAP needs in a buffer.

This is made up of HCI type(1), len(2), handle(2), L2CAP len(2), CID(2), control(2) and SDU length(2)

L2CAP_BLE_CONN_MIN_OFFSET

HCI type(1), len(2), handle(2), L2CAP len(2) and CID(2)

L2CAP_DEFAULT_BLE_CB_POOL_ID

Use the default HCI ACL buffer pool.

L2CAP_BLE_COC_SDU_OFFSET

to provide upper layer some minimal offset possibly required to process incoming packets

L2CAP_BROADCAST_MIN_OFFSET

Minimum offset for broadcast needs another two bytes for the PSM.

Typedefs

typedef uint16_t wiced_bt_l2cap_ch_cfg_bits_t

Channel configuration fields in bit map.

Refer L2CAP channel configuration

typedef uint8_t wiced_bt_l2cap_chnl_priority_t

Values for priority parameter to wiced_bt_l2cap_set_tx_priority().

Refer L2CAP channel transmission priority

void() wiced_bt_l2cap_connected_cback_t (wiced_bt_device_address_t bd_addr, uint16_t local_cid, uint16_t peer_mtu)

Connection established callback prototype.

Parameters

• bd_addr – : BD Address of remote

• local_cid – : Local CID assigned to the connection

• peer_mtu – : Peer MTU

Returns

void

void() wiced_bt_l2cap_disconnect_indication_cback_t (uint16_t local_cid, wiced_bool_t ack)

Disconnect indication callback prototype.

Parameters

• local_cid – : Local CID

• ack – : Boolean whether upper layer should ack this

Returns

void

void() wiced_bt_l2cap_disconnect_confirm_cback_t (uint16_t local_cid, uint16_t result)

Disconnect confirm callback prototype.

Parameters

• local_cid – : Local CID

• result – : Result

Returns

void

void() wiced_bt_l2cap_data_indication_cback_t (uint16_t local_cid, tDRB *p_drb)

Data received indication callback prototype.

Parameters

• local_cid – : Local CID

• p_buff – : Pointer to the data

• buf_len – : Length of the data

Returns

void

void() wiced_bt_l2cap_tx_complete_cback_t (uint16_t local_cid, void *p_data)

Transmit complete callback protype.

This callback is optional. If set, L2CAP will call it when packets are sent or flushed. If the count is 0xFFFF, it means all packets are sent for that CID (eRTM mode only).

Parameters

• local_cid – : Local CID

• p_buff – : Pointer to the data that was sent

Returns

void

void() wiced_bt_l2cap_fixed_chnl_cback_t (wiced_bt_device_address_t bd_addr, wiced_bool_t connected, uint16_t reason, wiced_bt_transport_t transport)

Fixed channel connected and disconnected.

Parameters

• bd_addr – : BD Address of remote

• connected – : TRUE if channel is connected, FALSE if disconnected

• reason – : Reason for connection failure

• transport – : Bluetooth Transport (BR/EDR or LE)

Returns

void

void() wiced_bt_l2cap_fixed_data_cback_t (wiced_bt_device_address_t bd_addr, uint8_t *p_data, uint16_t data_len)

Signalling data received.

Parameters

• bd_addr – : BD Address of remote

• p_buff – : Pointer to data

• data_len – : Data length

Returns

void

void() wiced_bt_l2cap_le_connect_indication_cback_t (wiced_bt_device_address_t bd_addr, uint16_t local_cid, uint16_t psm, uint8_t id, uint16_t mtu_peer)

LE Connection indication callback prototype.

Parameters

• bd_addr – : BD Address of remote

• local_cid – : Local CID assigned to the connection

• psm – : PSM that the remote wants to connect to

• id – : Identifier that the remote sent

• mtu_peer – : MTU of the peer

Returns

void

void() wiced_bt_l2cap_drb_release_cb (tDRB *p_drb)

User DRB may be released callback prototype.

This function address is passed in when the user provides a DRB for an eRTM or LE-COC channel. It is called when the DRB can be released, i.e. at the end of the connection.

Parameters

p_drb – : Address of the DRB that can be released

Returns

void

void() wiced_bt_l2cap_le_connect_confirm_cback_t (uint16_t local_cid, uint16_t result, uint16_t mtu_peer)

LE Connection confirmation callback prototype.

Parameters

• local_cid – : Local CID

• result – : Result - 0 = connected, non-zero means failure reason

• mtu_peer – : MTU of the peer

Returns

void

struct wiced_bt_l2cap_fcr_options_t

#include <>

Structure for Enhanced Retransmission Mode Options Refer to Volume 3, Part A, section 5.4 of BT Core specification for details.

Public Members

uint8_t mode

Requested mode of link.

L2CAP FCR mode

uint8_t tx_window_size

Maximum transmit window size (1..63)

uint8_t max_transmit

Maximum number of trasmission attempts.

uint16_t rtrans_timeout_ms

Retransmission timeout (msecs)

uint16_t monitor_timeout_ms

Monitor timeout (msecs)

uint16_t max_rx_pdu_size

Maximum PDU payload size.

struct wiced_bt_l2cap_cfg_information_t

#include <>

Define a structure to hold the configuration parameters.

Since the parameters are optional, for each parameter there is a boolean to use to signify its presence or absence. Refer to Volume 3, Part A, section 5.4 of BT Core specification for details

Public Members

uint16_t result

Only used in confirm messages.

wiced_bool_t mtu_present

TRUE if MTU option present.

uint16_t mtu

Maximum transmission unit size.

wiced_bool_t qos_present

QoS configuration present.

wiced_bt_flow_spec_t qos

QoS configuration.

wiced_bool_t flush_timeout_present

TRUE if flush option present.

uint16_t flush_timeout

Flush timeout value (1 msec increments)

wiced_bool_t fcr_present

TRUE if Enhanced retransmission & flow control option present.

wiced_bt_l2cap_fcr_options_t fcr

Enhanced flow control and retransmission parameters.

wiced_bool_t fcs_present

TRUE if Frame check sequence option present.

uint8_t fcs

‘0’ if desire is to bypass FCS, otherwise ‘1’

uint16_t flags

bit 0: 0-no continuation, 1-continuation

struct wiced_bt_l2cap_ertm_information_t

#include <>

Structure that applications use to create or accept connections with enhanced retransmission mode.

Public Members

uint8_t preferred_mode

Preferred mode: ERTM, Streaming, or Basic.

uint8_t allowed_modes

Bitmask for allowed modes.

Refer bit mask values in L2CAP FCR mode

struct wiced_bt_l2cap_appl_information_t

#include <>

Define the structure that applications use to register with L2CAP.

This structure includes callback functions. All functions MUST be provided. Additionally, if registering client for dynamic PSM, connect_ind_cb() must be NULL since dynamic PSMs use this as a flag for “virtual PSM”.

Public Members

wiced_bt_l2cap_connected_cback_t *connected_cback

BR/EDR connected event.

wiced_bt_l2cap_disconnect_indication_cback_t *disconnect_indication_cback

BR/EDR disconnect indication event.

wiced_bt_l2cap_disconnect_confirm_cback_t *disconnect_confirm_cback

BR/EDR disconnect confirmation event.

wiced_bt_l2cap_data_indication_cback_t *data_indication_cback

BR/EDR data received indication.

wiced_bt_l2cap_tx_complete_cback_t *tx_complete_cback

BR/EDR transmit complete event.

uint16_t mtu

Maximum transmission unit size.

uint8_t security_required

Security requirement.

uint8_t qos_present

QoS configuration present.

uint8_t flush_timeout_present

TRUE if flush option present.

uint8_t fcs_present

TRUE if Frame check sequence option present.

uint8_t is_ob_only

Set to TRUE if registration is for outbound only to a dynamic PSM.

wiced_bt_flow_spec_t qos

QoS configuration.

uint16_t flush_timeout

Flush timeout value (1 msec increments)

uint8_t fcr_allowed_modes

Set to 0 or L2CAP_FCR_CHAN_OPT_BASIC for no FCR.

wiced_bt_l2cap_fcr_options_t fcr

Enhanced flow control and retransmission parameters.

uint8_t fcs

‘0’ if desire is to bypass FCS, otherwise ‘1’

struct wiced_bt_l2cap_le_appl_information_t

#include <>

Define the structure that applications use to register with LE L2CAP.

This structure includes callback functions. All functions MUST be provided, with the exception of the “connect pending” callback. Additionally, if registering client for dynamic PSM, connect_ind_cb() must be NULL since dynamic PSMs use this as a flag for “virtual PSM”.

Public Members

wiced_bt_l2cap_le_connect_indication_cback_t *le_connect_indication_cback

LE connect indication event.

wiced_bt_l2cap_le_connect_confirm_cback_t *le_connect_confirm_cback

LE connect confirm event.

wiced_bt_l2cap_disconnect_indication_cback_t *disconnect_indication_cback

LE disconnect indication event.

wiced_bt_l2cap_disconnect_confirm_cback_t *disconnect_confirm_cback

LE disconnect confirm event.

wiced_bt_l2cap_data_indication_cback_t *data_indication_cback

LE data received indication.

wiced_bt_l2cap_tx_complete_cback_t *le_tx_complete_cback

LE tx complete.

wiced_bt_l2cap_drb_release_cb *le_release_drb_cb

LE DRB can be released.

struct wiced_bt_l2cap_fixed_chnl_reg_t

#include <>

Fixed channel registration info (the callback addresses and channel config)

Public Members

uint16_t channel_id

Fixed channel ID.

uint16_t default_idle_timeout

default idle timeout

wiced_bt_l2cap_fixed_chnl_cback_t *fixed_conn_cback

Connected callback.

wiced_bt_l2cap_fixed_data_cback_t *fixed_data_cback

Data received callback.

wiced_bt_l2cap_tx_complete_cback_t *fixed_tx_complete_cback

TX complete callback.