ble_l2cap.h

Go to the documentation of this file.

/**
 ****************************************************************************************
 *
 * @file ble_l2cap.h
 *
 * @brief BLE L2CAP API
 *
 ****************************************************************************************
 * @attention
  #####Copyright (c) 2019 GOODIX
  All rights reserved.
 
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:
  * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
  * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.
  * Neither the name of GOODIX nor the names of its contributors may be used
    to endorse or promote products derived from this software without
    specific prior written permission.
 
  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  POSSIBILITY OF SUCH DAMAGE.
 *****************************************************************************************
 */
 
  /**
 * @addtogroup BLE
 * @{
 */
 
 /**
  @addtogroup BLE_L2CAP Logical Link Control and Adaptation Protocol (L2CAP)
  @{
  @brief Definitions and prototypes for the L2CAP interface.
 */
 
#ifndef __BLE_L2CAP_H__
#define __BLE_L2CAP_H__
 
#include "ble_error.h"
#include "gr55xx_sys_cfg.h"
#include <stdint.h>  
#include <stdbool.h>
 
/**@addtogroup BLE_L2CAP_ENUMERATIONS Enumerations
 * @{ */
 
/**@brief LE credit based disconnection reasons. */
typedef enum
{
    BLE_L2CAP_REMOTE_USER_TERM_CON = 0x00,       /**< Remote user terminates the connection. */
    BLE_L2CAP_LOCAL_USER_TERM_CON  = 0x01,       /**< Local user terminates the connection. */
} ble_l2cap_lecb_disconn_reason_t;
 
/** @} */
 
/** @addtogroup BLE_L2CAP_STRUCTURES Structures
 * @{ */
/** @brief The parameter of LE credit based connection request packet sending. 
  * @note  The le_psm should be registered by the peer device, otherwise the peer device will reject this request with result of LE_PSM not supported.
  * @note  The local_cid should be 0x0040-0x007F. If the local_cid is set to 0, the stack will assign it dynamically. 
  * @note  The local_credit is required to be sure that at least one SDU can be received, otherwise the stack will use the default value: (MTU  + MPS + 1) /MPS + 1.
  * @note  The MTU range is [23~max_mtu].
  * @note  The MPS range is [23~max_mps].
  * @note  About max_mtu and max_mps config, please see @ref ble_gap_l2cap_params_set. 
*/
typedef struct
{
    uint16_t le_psm;             /**< The le_psm number. */
    uint16_t local_cid;          /**< The local CID. */
    uint16_t local_credits;      /**< The local credits indicate the number of LE-frames that the peer device can send to the L2CAP layer entity sending the LE Credit Based Connection Request. */
    uint16_t mtu;                /**< The MTU field specifies the maximum SDU size (in octets) that the L2CAP layer entity sending the LE Credit Based Connection Request can receive on this channel. */
    uint16_t mps;                /**< The MPS field specifies the maximum payload size (in octets) that the L2CAP layer entity sending the LE Credit Based Connection Request is capable of receiving on this channel. */
} ble_l2cap_lecb_conn_req_t;
 
/** @brief LE credit based connection confirm parameter. 
  * @note  The accept flag indicates whether the App accepts the LE Credit Based connection request.
  * @note  The peer_cid represents the channel endpoint on the peer device.
  * @note  The local_cid should be 0x0040-0x007F. If the local_cid is set to 0, the stack will assign it dynamically.
  * @note  The local_credits required to be sure that at least one SDU can be received, otherwise the stack will use the default value: (MTU  + MPS + 1) /MPS + 1.
  * @note  The MTU range is [23~max_mtu].
  * @note  The MPS range is [23~max_mps].
  * @note  About the max_mtu and max_mps config, please see @ref ble_gap_l2cap_params_set.
*/
typedef struct
{
    bool     accept;             /**< Whether to accept the connection request. */
    uint16_t peer_cid;           /**< It represents the channel endpoint on the device sending the request and receiving the response. */
    uint16_t local_cid;          /**< Local CID. */
    uint16_t local_credits;      /**< It indicates the number of LE-frames that the peer device can send to the L2CAP layer entity  sending the LE Credit Based Connection Respone. */
    uint16_t mtu;                /**< The MTU field specifies the maximum SDU size (in octets) that the L2CAP layer entity sending 
                                      the LE Credit Based Connection Request can receive on this channel. */
    uint16_t mps;                /**< The MPS field specifies the maximum payload size (in octets) that the L2CAP layer entity sending 
                                      the LE Credit Based Connection Request is capable of receiving on this channel. */
} ble_l2cap_lecb_cfm_conn_t;
 
/** @brief LE flow control credit packet parameter.  */
typedef struct
{
    uint16_t local_cid;      /**< The local source channel ID. */
    uint16_t credits;        /**< Number of credits that the receiving device can increment. */
} ble_l2cap_lecb_add_credits_t;
 
/** @brief SDU packet parameter. 
  * @note  The length should be less than peer_mtu when sending sdu packet.
  * @note  The credits is 0 if this packet is being sent, or it represents the number of credits consumed by this sdu if this packet is received.
  * @note  When the application receives a sdu, it should firstly copy this sdu packet before handling it, because the stack will free it after invoking the callback function.
  * @note  Similarly, the application should free the packet if it is malloced after invoking the function to send sdu packet.
*/
typedef struct
{
    uint16_t  cid;                 /**< The local source channel. */
    uint16_t  credits;             /**< The credits is 0 if this packet is being sent, otherwise it represents the number of credits consumed by the sdu. */
    uint16_t  length;              /**< The lenght of data. */
    uint8_t  *data;                /**< The data of this sdu packet. */
} ble_l2cap_lecb_sdu_t;
 
/** @brief L2cap Connect Request event for @ref BLE_L2CAP_EVT_CONN_REQ. */
typedef struct
{
    uint16_t le_psm;   /**< Le_psm number that should be registered by local device. */
    uint16_t peer_cid; /**< It represents the channel endpoint on the device sending the request and receiving the response. */
    uint16_t peer_mtu; /**< It indicates the maximum SDU size (in octets) that the L2CAP layer entity sending the LE Credit 
                            Based Connection Request can receive on this channel.  */
    uint16_t peer_mps; /**< It indicates the maximum payload size (in octets) that the L2CAP layer entity sending the LE Credit 
                            Based Connection Request is capable of receiving on this channe. */
} ble_l2cap_evt_conn_req_t;
 
/** @brief L2cap Connected Indicate event for @ref BLE_L2CAP_EVT_CONN_IND. */
typedef struct
{
    uint16_t le_psm;        /**< Le_psm number. */
    uint16_t local_cid;     /**< The local source channel ID. */
    uint16_t local_credits; /**< It indicates the number of LE-frames that the local device can receive. */
    uint16_t peer_credits;  /**< It indicates the number of LE-frames that the peer device can receive. */
    uint16_t peer_mtu;      /**< It indicates the maximum SDU size (in octets) that the L2CAP layer entity sending the LE Credit 
                                 Based Connection Request can receive on this channel.  */
    uint16_t peer_mps;      /**< It indicates the maximum payload size (in octets) that the L2CAP layer entity sending the LE Credit 
                                 Based Connection Request is capable of receiving on this channe. */
} ble_l2cap_evt_conn_ind_t;
 
/** @brief L2cap Credits Add Indicate event for @ref BLE_L2CAP_EVT_ADD_CREDITS_IND. */
typedef struct
{
    uint16_t local_cid;                 /**< The local source channel ID. */
    uint16_t peer_added_credits;        /**< Represent number of credits the receiving device can increment. */
} ble_l2cap_evt_add_credits_ind_t;
 
/** @brief L2cap disconnect event for @ref BLE_L2CAP_EVT_DISCONNECTED. */
typedef struct
{
    uint16_t                         local_cid;              /**< The local source channel ID. */
    ble_l2cap_lecb_disconn_reason_t  reason;                 /**< The reason for disconnection, see @ref ble_l2cap_lecb_disconn_reason_t . */
} ble_l2cap_evt_disconnect_t;
 
/**@brief L2cap SDU Receive event for @ref BLE_L2CAP_EVT_SDU_RECV. */
typedef struct
{
    uint16_t  cid;                 /**< The local source channel. */
    uint16_t  credits;             /**< The credits is 0 if this packet is being sent, otherwise it represents the number of credits consumed by the sdu. */
    uint16_t  length;              /**< The lenght of data. */
    uint8_t  *data; /**< The data of this sdu packet. */
} ble_l2cap_evt_sdu_recv_t;
 
/**@brief L2cap SDU Send event for @ref BLE_L2CAP_EVT_SDU_SEND. */
typedef struct
{ 
    uint16_t     cid;            /**< Channel ID that is the local CID. */
    uint16_t     credits;        /**< Number of peer credit used. */
}ble_l2cap_evt_sdu_send_t;
 
/**@brief L2cap Credits Add Completed event for @ref BLE_GATTC_EVT_NTF_IND. */
typedef struct
{ 
    uint16_t     local_cid;            /**< Channel ID that is the local CID. */
}ble_l2cap_evt_add_credits_cplt_t;
 
/**@brief BLE L2cap event structure. */
typedef struct
{
    uint8_t  index;                                             /**< Index of connection or advertising. */
    union
    {
        ble_l2cap_evt_conn_req_t         conn_req;              /**< L2cap Connect Request event. */
        ble_l2cap_evt_conn_ind_t         conn_ind;              /**< L2cap Connected Indicate event. */
        ble_l2cap_evt_add_credits_ind_t  add_credits_ind;       /**< L2cap Credits Add Indicate event. */
        ble_l2cap_evt_disconnect_t       disconnected;          /**< L2cap Disconnected event. */
        ble_l2cap_evt_sdu_recv_t         sdu_recv;              /**< L2cap SDU Receive event. */
        ble_l2cap_evt_sdu_send_t         sdu_send;              /**< L2cap SDU Send event. */
        ble_l2cap_evt_add_credits_cplt_t add_credits_cplt;      /**< L2cap Credits Add Completed event. */
    } params;                                                   /**< Event Parameters. */
} ble_l2cap_evt_t;
/** @} */
 
/** @addtogroup BLE_L2CAP_FUNCTIONS Functions
 * @{ */
/**
 ****************************************************************************************
 * @brief Create the LE credit based connection.
 *
 * @param[in] conn_idx:   ACL connection index. The first ACL connection index is 0, and the index will be increased one by one.
 * @param[in] p_conn_req: Pointer to the LE Credit Based Connection Request structure.
 *
 * @retval ::SDK_SUCCESS: The LE Credit Based connection request is successfully set to the BLE stack.
 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
 ****************************************************************************************
 */
uint16_t ble_l2cap_lecb_conn_create(uint8_t conn_idx, const ble_l2cap_lecb_conn_req_t *p_conn_req);
 
/**
 ****************************************************************************************
 * @brief Confirm the LE credit based connection after receiving the connection request packet from the peer device.
 *
 * @param[in] conn_idx:   ACL connection index. The first ACL connection index is 0 and the index will be increased one by one.
 * @param[in] p_cfm_conn: Pointer to the LE Credit Based Connection Confirm structure.
 *
 * @retval ::SDK_SUCCESS: The LE Credit Based connection confirmation is successfully set to the BLE stack.
 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied.
 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
 ****************************************************************************************
 */
uint16_t ble_l2cap_lecb_conn_cfm(uint8_t conn_idx, const ble_l2cap_lecb_cfm_conn_t *p_cfm_conn);
 
/**
 ****************************************************************************************
 * @brief Disconnect the LE credit based connection.
 *
 * @param[in] conn_idx:  ACL connection index. The first ACL connection index is 0 and the index will be increased one by one.
 * @param[in] local_cid: The local source channel ID.
 *
 * @retval ::SDK_SUCCESS: LE Credit Based disconnection request is successfully set to the BLE stack.
 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
 ****************************************************************************************
 */
uint16_t ble_l2cap_lecb_disconnect(uint8_t conn_idx, uint16_t local_cid);
 
/**
 ****************************************************************************************
 * @brief Send a LE Flow Control Credit packet when the device is capable of receiving additional LE-frames (for example after the device has processed the sdu).
 *
 * @param[in] conn_idx:      ACL connection index, the first ACL connection index is 0, and increased one by one.
 * @param[in] p_add_credits: Pointer to the LE Flow Control Credit structure.
 *
 * @retval ::SDK_SUCCESS: LE Flow Control Credit packet is successfully set to the BLE stack.
 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
 ****************************************************************************************
 */
uint16_t ble_l2cap_lecb_credits_add(uint8_t conn_idx, const ble_l2cap_lecb_add_credits_t *p_add_credits);
 
/**
 ****************************************************************************************
 * @brief Send an SDU packet to the peer device.
 *
 * @param[in] conn_idx: ACL connection index. The first ACL connection index is 0 and the index will be increased one by one.
 * @param[in] p_sdu:    Pointer to the sdu packet structure.
 *
 * @retval ::SDK_SUCCESS: The sdu packet is successfully set to the BLE stack.
 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
 ****************************************************************************************
 */
uint16_t ble_l2cap_lecb_sdu_send(uint8_t conn_idx, const ble_l2cap_lecb_sdu_t *p_sdu);
 
/**
 ****************************************************************************************
 * @brief Register PSM.
 *
 * @param[in] le_psm: The le_psm number.
 *
 * @retval ::SDK_SUCCESS: The callback is successfully registered to the BLE stack.
 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied.
 * @retval ::SDK_ERR_INVALID_PSM_EXCEEDED_MAX_PSM_NUM: The maximum PSM number limit is exceeded.
 ****************************************************************************************
 */
uint16_t ble_l2cap_lecb_psm_register(uint16_t le_psm);
/** @} */
 
#endif
 
/**
  @}
*/
/** @} */