espressif/esp-nimble
1
0
Fork 0
mirror of https://github.com/espressif/esp-nimble.git synced 2026-06-06 05:14:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

host/l2cap: add doxygen comments for the header file

Browse Source 
Adds missing macros, structures and functions documentation.
This commit is contained in:
Wojciech Pietraszewski
2023-06-19 16:26:34 +02:00
committed by Szymon Janc
parent 4cf74c3bf5
commit 765f9d97ba
1 changed files with 366 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
nimble/host/include/host/ble_l2cap.h
+366 -2
View File
@@ -17,6 +17,20 @@
* under the License.
*/
/**
* @file ble_l2cap.h
*
* @brief L2CAP (Logical Link Control and Adaptation Protocol) API
*
* This header file provides the public API for interacting with the L2CAP layer of the BLE
* (Bluetooth Low Energy) stack. L2CAP is responsible for managing logical channels between
* two connected BLE devices.
*
* @defgroup bt_host_l2cap Bluetooth Host Logical Link Control and Adaptation Protocol
* @ingroup bt_host
* @{
*/
#ifndef H_BLE_L2CAP_
#define H_BLE_L2CAP_
@@ -25,89 +39,311 @@
extern "C" {
#endif
/**
* @brief L2CAP Signaling Connection Parameters Update Request.
*
* This structure represents a request to update the L2CAP connection parameters.
*/
struct ble_l2cap_sig_update_req;
/**
* @brief BLE Host Connection structure.
*
* This structure represents a connection between the BLE host and a remote device.
*/
struct ble_hs_conn;
/**
* @defgroup ble_l2cap_channel_ids Channel Identifiers
* @{
*/
/** Attribute Protocol (ATT) CID. */
#define BLE_L2CAP_CID_ATT 4
/** L2CAP LE Signaling CID. */
#define BLE_L2CAP_CID_SIG 5
/** Security Manager (SM) CID. */
#define BLE_L2CAP_CID_SM 6
/** @} */
/**
* @defgroup ble_l2cap_signaling_op_codes Signaling Commands Operation Codes
* @{
*/
/** Reject */
#define BLE_L2CAP_SIG_OP_REJECT 0x01
/** Connect Request */
#define BLE_L2CAP_SIG_OP_CONNECT_REQ 0x02
/** Connect Response */
#define BLE_L2CAP_SIG_OP_CONNECT_RSP 0x03
/** Configuration Request */
#define BLE_L2CAP_SIG_OP_CONFIG_REQ 0x04
/** Configuration Response */
#define BLE_L2CAP_SIG_OP_CONFIG_RSP 0x05
/** Disconnect Request */
#define BLE_L2CAP_SIG_OP_DISCONN_REQ 0x06
/** Disconnect Response */
#define BLE_L2CAP_SIG_OP_DISCONN_RSP 0x07
/** Echo Request */
#define BLE_L2CAP_SIG_OP_ECHO_REQ 0x08
/** Echo Response */
#define BLE_L2CAP_SIG_OP_ECHO_RSP 0x09
/** Information Request */
#define BLE_L2CAP_SIG_OP_INFO_REQ 0x0a
/** Information Response */
#define BLE_L2CAP_SIG_OP_INFO_RSP 0x0b
/** Create Channel Request */
#define BLE_L2CAP_SIG_OP_CREATE_CHAN_REQ 0x0c
/** Create Channel Response */
#define BLE_L2CAP_SIG_OP_CREATE_CHAN_RSP 0x0d
/** Move Channel Request */
#define BLE_L2CAP_SIG_OP_MOVE_CHAN_REQ 0x0e
/** Move Channel Response */
#define BLE_L2CAP_SIG_OP_MOVE_CHAN_RSP 0x0f
/** Move Channel Confirmation Request */
#define BLE_L2CAP_SIG_OP_MOVE_CHAN_CONF_REQ 0x10
/** Move Channel Confirmation Response */
#define BLE_L2CAP_SIG_OP_MOVE_CHAN_CONF_RSP 0x11
/** Update Request */
#define BLE_L2CAP_SIG_OP_UPDATE_REQ 0x12
/** Update Response */
#define BLE_L2CAP_SIG_OP_UPDATE_RSP 0x13
/** LE Credit Based Connection Request */
#define BLE_L2CAP_SIG_OP_LE_CREDIT_CONNECT_REQ 0x14
/** LE Credit Based Connection Response */
#define BLE_L2CAP_SIG_OP_LE_CREDIT_CONNECT_RSP 0x15
/** Credit Based Flow Control Credit */
#define BLE_L2CAP_SIG_OP_FLOW_CTRL_CREDIT 0x16
/** Credit Based Connection Request */
#define BLE_L2CAP_SIG_OP_CREDIT_CONNECT_REQ 0x17
/** Credit Based Connection Response */
#define BLE_L2CAP_SIG_OP_CREDIT_CONNECT_RSP 0x18
/** Credit Based Reconfiguration Request */
#define BLE_L2CAP_SIG_OP_CREDIT_RECONFIG_REQ 0x19
/** Credit Based Reconfiguration Response */
#define BLE_L2CAP_SIG_OP_CREDIT_RECONFIG_RSP 0x1A
/** Signaling Command Maximum Value */
#define BLE_L2CAP_SIG_OP_MAX 0x1B
/** @} */
/**
* @defgroup ble_l2cap_signaling_err_codes Signaling Commands Error Codes
* @{
*/
/** Command Not Understood */
#define BLE_L2CAP_SIG_ERR_CMD_NOT_UNDERSTOOD 0x0000
/** Maximum Transmission Unit (MTU) Exceeded */
#define BLE_L2CAP_SIG_ERR_MTU_EXCEEDED 0x0001
/** Invalid CID */
#define BLE_L2CAP_SIG_ERR_INVALID_CID 0x0002
/** @} */
/**
* @defgroup ble_l2cap_coc_err_codes Connection-Oriented Channels (CoC) Error Codes
* @{
*/
/** Connection Success */
#define BLE_L2CAP_COC_ERR_CONNECTION_SUCCESS 0x0000
/** Unknown LE Protocol/Service Multiplexer (PSM) */
#define BLE_L2CAP_COC_ERR_UNKNOWN_LE_PSM 0x0002
/** No Resources */
#define BLE_L2CAP_COC_ERR_NO_RESOURCES 0x0004
/** Insufficient Authentication */
#define BLE_L2CAP_COC_ERR_INSUFFICIENT_AUTHEN 0x0005
/** Insufficient Authorization */
#define BLE_L2CAP_COC_ERR_INSUFFICIENT_AUTHOR 0x0006
/** Insufficient Key Size */
#define BLE_L2CAP_COC_ERR_INSUFFICIENT_KEY_SZ 0x0007
/** Insufficient Encryption */
#define BLE_L2CAP_COC_ERR_INSUFFICIENT_ENC 0x0008
/** Invalid Source CID */
#define BLE_L2CAP_COC_ERR_INVALID_SOURCE_CID 0x0009
/** Source CID Already Used */
#define BLE_L2CAP_COC_ERR_SOURCE_CID_ALREADY_USED 0x000A
/** Unacceptable Parameters */
#define BLE_L2CAP_COC_ERR_UNACCEPTABLE_PARAMETERS 0x000B
/** Invalid Parameters */
#define BLE_L2CAP_COC_ERR_INVALID_PARAMETERS 0x000C
/** @} */
/**
* @defgroup ble_l2cap_reconfig_err_codes Channel Reconfiguration Error Codes
* @{
*/
/** Reconfiguration Succeeded */
#define BLE_L2CAP_ERR_RECONFIG_SUCCEED 0x0000
/** Reduction of Maximum Transmission Unit (MTU) Not Allowed */
#define BLE_L2CAP_ERR_RECONFIG_REDUCTION_MTU_NOT_ALLOWED 0x0001
/** Reduction of Maximum Packet Size (MPS) Not Allowed */
#define BLE_L2CAP_ERR_RECONFIG_REDUCTION_MPS_NOT_ALLOWED 0x0002
/** Invalid Destination CID */
#define BLE_L2CAP_ERR_RECONFIG_INVALID_DCID 0x0003
/** Unaccepted Parameters */
#define BLE_L2CAP_ERR_RECONFIG_UNACCEPTED_PARAM 0x0004
/** @} */
/**
* @defgroup ble_l2cap_coc_event_types Connection-Oriented Channel (CoC) Event Types
* @{
*/
/** CoC Connected */
#define BLE_L2CAP_EVENT_COC_CONNECTED 0
/** CoC Disconnected */
#define BLE_L2CAP_EVENT_COC_DISCONNECTED 1
/** CoC Accept */
#define BLE_L2CAP_EVENT_COC_ACCEPT 2
/** CoC Data Received */
#define BLE_L2CAP_EVENT_COC_DATA_RECEIVED 3
/** CoC Transmission Unstalled */
#define BLE_L2CAP_EVENT_COC_TX_UNSTALLED 4
/** CoC Reconfiguration Completed */
#define BLE_L2CAP_EVENT_COC_RECONFIG_COMPLETED 5
/** CoC Peer Reconfigured */
#define BLE_L2CAP_EVENT_COC_PEER_RECONFIGURED 6
/** @} */
/**
* @brief Function signature for L2CAP signaling update event callback.
*
* This function is used to handle signaling update events in the L2CAP layer,
* such as changes in connection parameters.
*
* @param conn_handle The connection handle associated with the signaling update event.
* @param status The status of the signaling update event.
* @param arg A pointer to additional arguments passed to the callback function.
*/
typedef void ble_l2cap_sig_update_fn(uint16_t conn_handle, int status,
void *arg);
/**
* @brief Represents the signaling update in L2CAP.
*
* This structure holds the parameters required for initiating a signaling update in the L2CAP layer.
* It defines the connection interval, slave latency, and supervision timeout multiplier for the update.
*/
struct ble_l2cap_sig_update_params {
/**
* The minimum desired connection interval in increments of 1.25 ms.
* This value defines the lower bound for the connection interval range.
*/
uint16_t itvl_min;
/**
* The maximum desired connection interval in increments of 1.25 ms.
* This value defines the upper bound for the connection interval range.
*/
uint16_t itvl_max;
/**
* The desired number of connection events that a slave device can skip.
* It specifies the maximum allowed latency between consecutive connection events.
*/
uint16_t slave_latency;
/**
* The desired supervision timeout multiplier.
* The supervision timeout defines the time limit for detecting the loss of a connection.
* This value is multiplied by the connection interval to determine the supervision timeout duration.
*/
uint16_t timeout_multiplier;
};
/**
* @brief Initiate an L2CAP connection update procedure.
*
* This function initiates an L2CAP connection update procedure for the specified connection handle.
* The update procedure is used to modify the connection parameters, such as interval, latency, and timeout.
*
* @param conn_handle The connection handle of the L2CAP connection.
*
* @param params A pointer to a structure containing the desired update parameters.
* This includes the new connection interval, slave latency, and
* supervision timeout multiplier.
*
* @param cb The callback function to be called when the update request completes.
* The function signature for the callback is defined by `ble_l2cap_sig_update_fn`.
*
* @param cb_arg An optional argument to be passed to the callback function.
*
* @return 0 on success;
* A non-zero value on failure.
*/
int ble_l2cap_sig_update(uint16_t conn_handle,
struct ble_l2cap_sig_update_params *params,
ble_l2cap_sig_update_fn *cb, void *cb_arg);
/**
* @brief Structure representing a L2CAP channel.
*
* It is used to maintain the state and track the properties of an L2CAP channel
* during its lifecycle.
*/
struct ble_l2cap_chan;
/**
* Represents a L2CAP-related event.
* @brief Represents a L2CAP-related event.
*
* When such an event occurs, the host notifies the application by passing an
* instance of this structure to an application-specified callback.
*/
@@ -234,33 +470,161 @@ struct ble_l2cap_event {
};
};
/**
* @brief Represents information about an L2CAP channel.
*
* This structure is typically used to retrieve or provide information about an existing L2CAP channel.
*/
struct ble_l2cap_chan_info {
/** Source Channel Identifier. */
uint16_t scid;
/** Destination Channel Identifier. */
uint16_t dcid;
/** Local L2CAP Maximum Transmission Unit. */
uint16_t our_l2cap_mtu;
/** Peer L2CAP Maximum Transmission Unit. */
uint16_t peer_l2cap_mtu;
/** Protocol/Service Multiplexer of the channel. */
uint16_t psm;
/** Local CoC Maximum Transmission Unit. */
uint16_t our_coc_mtu;
/** Peer CoC Maximum Transmission Unit. */
uint16_t peer_coc_mtu;
};
/**
* @brief Function pointer type for handling L2CAP events.
*
* @param event A pointer to the L2CAP event structure.
* @param arg A pointer to additional arguments passed to the callback function.
*
* @return Integer value representing the status or result of the event handling.
*/
typedef int ble_l2cap_event_fn(struct ble_l2cap_event *event, void *arg);
/**
* @brief Get the connection handle associated with an L2CAP channel.
*
* This function retrieves the connection handle associated with the specified L2CAP channel.
*
* @param chan A pointer to the L2CAP channel structure.
*
* @return The connection handle associated with the L2CAP channel on success;
* A Bluetooth Host Error Code on failure:
* BLE_HS_CONN_HANDLE_NONE: if the provided channel pointer is NULL.
*/
uint16_t ble_l2cap_get_conn_handle(struct ble_l2cap_chan *chan);
/**
* @brief Create an L2CAP server.
*
* This function creates an L2CAP server with the specified Protocol/Service Multiplexer (PSM) and Maximum
* Transmission Unit (MTU) size. The server is used to accept incoming L2CAP connections from remote clients.
* When a connection request is received, the provided callback function will be invoked with the corresponding
* event information.
*
* @param psm The Protocol/Service Multiplexer (PSM) for the server.
* @param mtu The Maximum Transmission Unit (MTU) size for the server.
* @param cb Pointer to the callback function to be invoked when a connection request is received.
* @param cb_arg An optional argument to be passed to the callback function.
*
* @return 0 on success;
* A non-zero value on failure.
*/
int ble_l2cap_create_server(uint16_t psm, uint16_t mtu,
ble_l2cap_event_fn *cb, void *cb_arg);
/**
* @brief Initiate an L2CAP connection.
*
* This function initiates an L2CAP connection to a remote device with the specified connection handle,
* Protocol/Service Multiplexer (PSM), Maximum Transmission Unit (MTU) size, and receive SDU buffer.
* When the connection is established or if there is an error during the connection process, the provided
* callback function will be invoked with the corresponding event information.
*
* @param conn_handle The connection handle for the remote device.
* @param psm The Protocol/Service Multiplexer (PSM) for the connection.
* @param mtu The Maximum Transmission Unit (MTU) size for the connection.
* @param sdu_rx Pointer to the receive Service Data Unit (SDU) buffer.
* @param cb Pointer to the callback function to be invoked when the connection is established.
* @param cb_arg An optional argument to be passed to the callback function.
*
* @return 0 on success;
* A non-zero value on failure.
*/
int ble_l2cap_connect(uint16_t conn_handle, uint16_t psm, uint16_t mtu,
struct os_mbuf *sdu_rx,
ble_l2cap_event_fn *cb, void *cb_arg);
/**
* @brief Disconnect an L2CAP channel.
*
* This function disconnects the specified L2CAP channel by sending a disconnect signal.
*
* @param chan Pointer to the L2CAP channel structure representing the channel to disconnect.
*
* @return 0 on success;
* A non-zero value on failure.
*/
int ble_l2cap_disconnect(struct ble_l2cap_chan *chan);
/**
* @brief Send an SDU (Service Data Unit) over an L2CAP channel.
*
* This function sends an SDU over the specified L2CAP channel. The SDU is encapsulated
* in L2CAP frames and transmitted to the remote device.
*
* @param chan Pointer to the L2CAP channel structure representing the channel to send the SDU on.
* @param sdu_tx Pointer to the os_mbuf structure containing the SDU (Service Data Unit) to send.
*
* @return 0 on success;
* BLE_HS_ESTALLED: if there was not enough credits available to send whole SDU.
* The application needs to wait for the event 'BLE_L2CAP_EVENT_COC_TX_UNSTALLED'
* before being able to transmit more data;
* Another non-zero value on failure.
*/
int ble_l2cap_send(struct ble_l2cap_chan *chan, struct os_mbuf *sdu_tx);
/**
* @brief Check if the L2CAP channel is ready to receive an SDU.
*
* This function checks if the specified L2CAP channel is ready to receive an SDU (Service Data Unit).
* It can be used to determine if the channel is in a state where it can accept incoming data.
*
* @param chan Pointer to the L2CAP channel structure to check.
* @param sdu_rx Pointer to the os_mbuf structure to receive the incoming SDU.
*
* @return 0 if the channel is ready to receive an SDU;
* A non-zero value on failure.
*/
int ble_l2cap_recv_ready(struct ble_l2cap_chan *chan, struct os_mbuf *sdu_rx);
/**
* @brief Get information about an L2CAP channel.
*
* This function retrieves information about the specified L2CAP channel and populates
* the provided `ble_l2cap_chan_info` structure with the channel's details.
*
* @param chan Pointer to the L2CAP channel structure to retrieve information from.
* @param chan_info Pointer to the `ble_l2cap_chan_info` structure to populate with channel information.
*
* @return 0 on success;
* A non-zero value on failure.
*/
int ble_l2cap_get_chan_info(struct ble_l2cap_chan *chan, struct ble_l2cap_chan_info *chan_info);
#ifdef __cplusplus
}
#endif
/**
* @}
*/
#endif