ble_l2cap.h

00001 /* 
00002  * Copyright (c) Nordic Semiconductor ASA
00003  * All rights reserved.
00004  * 
00005  * Redistribution and use in source and binary forms, with or without modification,
00006  * are permitted provided that the following conditions are met:
00007  * 
00008  *   1. Redistributions of source code must retain the above copyright notice, this
00009  *   list of conditions and the following disclaimer.
00010  * 
00011  *   2. Redistributions in binary form must reproduce the above copyright notice, this
00012  *   list of conditions and the following disclaimer in the documentation and/or
00013  *   other materials provided with the distribution.
00014  * 
00015  *   3. Neither the name of Nordic Semiconductor ASA nor the names of other
00016  *   contributors to this software may be used to endorse or promote products
00017  *   derived from this software without specific prior written permission.
00018  * 
00019  *   4. This software must only be used in a processor manufactured by Nordic
00020  *   Semiconductor ASA, or in a processor manufactured by a third party that
00021  *   is used in combination with a processor manufactured by Nordic Semiconductor.
00022  * 
00023  * 
00024  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
00025  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00026  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00027  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
00028  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00029  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00030  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
00031  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00032  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00033  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00034  * 
00035  */
00036 
00037 /**
00038   @addtogroup BLE_L2CAP Logical Link Control and Adaptation Protocol (L2CAP)
00039   @{
00040   @brief Definitions and prototypes for the L2CAP interface.
00041  */
00042 
00043 #ifndef BLE_L2CAP_H__
00044 #define BLE_L2CAP_H__ 
00045 
00046 #include "ble_types.h"
00047 #include "ble_ranges.h"
00048 #include "ble_err.h"
00049 #include "nrf_svc.h"
00050 
00051 /**@addtogroup BLE_L2CAP_ENUMERATIONS Enumerations
00052  * @{ */
00053 
00054 /**@brief L2CAP API SVC numbers. */
00055 enum BLE_L2CAP_SVCS 
00056 {
00057   SD_BLE_L2CAP_CID_REGISTER = BLE_L2CAP_SVC_BASE,  /**< Register a CID. */
00058   SD_BLE_L2CAP_CID_UNREGISTER,                     /**< Unregister a CID. */
00059   SD_BLE_L2CAP_TX                                  /**< Transmit a packet. */
00060 };
00061 
00062 /**@brief L2CAP Event IDs. */
00063 enum BLE_L2CAP_EVTS 
00064 {
00065   BLE_L2CAP_EVT_RX  = BLE_L2CAP_EVT_BASE          /**< L2CAP packet received. */
00066 };
00067 
00068 /** @} */
00069 
00070 /**@addtogroup BLE_L2CAP_DEFINES Defines
00071  * @{ */
00072 
00073 /**@defgroup BLE_ERRORS_L2CAP SVC return values specific to L2CAP
00074  * @{ */
00075 #define BLE_ERROR_L2CAP_CID_IN_USE            (NRF_L2CAP_ERR_BASE + 0x000)  /**< CID already in use. */
00076 /** @} */
00077 
00078 /**@brief Default L2CAP MTU. */
00079 #define BLE_L2CAP_MTU_DEF           (23)    
00080 
00081 /**@brief Invalid Channel Identifier. */
00082 #define BLE_L2CAP_CID_INVALID       (0x0000) 
00083 
00084 /**@brief Dynamic Channel Identifier base. */
00085 #define BLE_L2CAP_CID_DYN_BASE      (0x0040) 
00086 
00087 /**@brief Maximum amount of dynamic CIDs. */
00088 #define BLE_L2CAP_CID_DYN_MAX       (8) 
00089 
00090 /** @} */
00091 
00092 /**@addtogroup BLE_L2CAP_STRUCTURES Structures
00093  * @{ */
00094 
00095 /**@brief Packet header format for L2CAP transmission. */
00096 typedef struct
00097 {
00098   uint16_t   len;                                 /**< Length of valid info in data member. */
00099   uint16_t   cid;                                 /**< Channel ID on which packet is transmitted. */
00100 } ble_l2cap_header_t;
00101 
00102 
00103 /**@brief L2CAP Received packet event report. */
00104 typedef struct
00105 {
00106   ble_l2cap_header_t header;                      /**< L2CAP packet header. */
00107   uint8_t    data[1];                             /**< Packet data, variable length. */
00108 } ble_l2cap_evt_rx_t;
00109 
00110 
00111 /**@brief L2CAP event callback event structure. */
00112 typedef struct
00113 {
00114   uint16_t conn_handle;                           /**< Connection Handle on which event occured. */
00115   union
00116   {
00117     ble_l2cap_evt_rx_t rx;                        /**< RX Event parameters. */
00118   } params;                                       /**< Event Parameters. */
00119 } ble_l2cap_evt_t;
00120 
00121 /** @} */
00122 
00123 /**@addtogroup BLE_L2CAP_FUNCTIONS Functions
00124  * @{ */
00125 
00126 /**@brief Register a CID with L2CAP.
00127  *
00128  * @details This registers a higher protocol layer with the L2CAP multiplexer, and is requried prior to all operations on the CID.
00129  *          
00130  * @param[in] cid L2CAP CID.
00131  *
00132  * @retval ::NRF_SUCCESS Successfully registered a CID with the L2CAP layer.
00133  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, CID must be above @ref BLE_L2CAP_CID_DYN_BASE.
00134  * @retval ::BLE_ERROR_L2CAP_CID_IN_USE L2CAP CID already in use.
00135  * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation.
00136  */
00137 SVCALL(SD_BLE_L2CAP_CID_REGISTER, uint32_t, sd_ble_l2cap_cid_register(uint16_t cid));
00138 
00139 /**@brief Unregister a CID with L2CAP.
00140  *
00141  * @details This unregisters a previously registerd higher protocol layer with the L2CAP multiplexer.
00142  *          
00143  * @param[in] cid L2CAP CID.
00144  *
00145  * @retval ::NRF_SUCCESS Successfully unregistered the CID.
00146  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
00147  * @retval ::NRF_ERROR_NOT_FOUND CID not previously registered.
00148  */
00149 SVCALL(SD_BLE_L2CAP_CID_UNREGISTER, uint32_t, sd_ble_l2cap_cid_unregister(uint16_t cid));
00150 
00151 /**@brief Transmit an L2CAP packet.
00152  *
00153  * @note    It is important to note that a call to this function will <b>consume an application buffer</b>, and will therefore 
00154  *          generate a @ref BLE_EVT_TX_COMPLETE event when the packet has been transmitted. 
00155  *          Please see the documentation of @ref sd_ble_tx_buffer_count_get for more details.
00156  *
00157  * @param[in] conn_handle Connection Handle.
00158  * @param[in] p_header    Pointer to a packet header containing length and CID.
00159  * @param[in] p_data      Pointer to the data to be transmitted.
00160  *
00161  * @retval ::NRF_SUCCESS Successfully queued an L2CAP packet for transmission.
00162  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00163  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, CIDs must be registered beforehand with @ref sd_ble_l2cap_cid_register.
00164  * @retval ::NRF_ERROR_NOT_FOUND CID not found.
00165  * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation.
00166  * @retval ::BLE_ERROR_NO_TX_BUFFERS Not enough application buffers available.
00167  * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied, see @ref BLE_L2CAP_MTU_DEF.
00168  */
00169 SVCALL(SD_BLE_L2CAP_TX, uint32_t, sd_ble_l2cap_tx(uint16_t conn_handle, ble_l2cap_header_t const *p_header, uint8_t const *p_data));
00170 
00171 /** @} */
00172 
00173 #endif // BLE_L2CAP_H__
00174 
00175 /**
00176   @}
00177 */