mlmr_c.h
Go to the documentation of this file.
1 /**
2  *****************************************************************************************
3  *
4  * @file mlmr_c.h
5  *
6  * @brief Header file - Multi Link Multi Role Service Client
7  *
8  *****************************************************************************************
9  * @attention
10  #####Copyright (c) 2019 GOODIX
11  All rights reserved.
12 
13  Redistribution and use in source and binary forms, with or without
14  modification, are permitted provided that the following conditions are met:
15  * Redistributions of source code must retain the above copyright
16  notice, this list of conditions and the following disclaimer.
17  * Redistributions in binary form must reproduce the above copyright
18  notice, this list of conditions and the following disclaimer in the
19  documentation and/or other materials provided with the distribution.
20  * Neither the name of GOODIX nor the names of its contributors may be used
21  to endorse or promote products derived from this software without
22  specific prior written permission.
23 
24  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27  ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
28  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34  POSSIBILITY OF SUCH DAMAGE.
35  *****************************************************************************************
36  */
37 
38 /**
39  * @addtogroup BLE_SRV BLE Services
40  * @{
41  * @brief Definitions and prototypes for the BLE Service interface.
42  */
43 
44 /**
45  * @defgroup BLE_SDK_MLMR_C Multi Link Multi Role Service Client (MLMR_C)
46  * @{
47  * @brief Multi Link Multi Role Service Client module.
48  *
49  * @details The Multi Link Multi Role Service Client contains the APIs and types, which can be used by the
50  * application to perform scanning, connection and discover Multi Link Multi Role Service at
51  * peer and interact with it.
52  *
53  * The application must provide an event handler, then call \ref mlmr_client_init(). After the
54  * module can send and receive BLE data, application can call \ref mlmr_c_tx_data_send() to
55  * send data to peer, and receive data from peer \ref MLMR_C_EVT_PEER_DATA_RECEIVE,
56  * meanwhile update its received BLE data state \ref mlmr_c_rx_flow_ctrl_set() to peer.
57  */
58 
59 #ifndef __MLMR_C_H__
60 #define __MLMR_C_H__
61 
62 #include "ble_prf_types.h"
63 #include "gr_includes.h"
64 #include "custom_config.h"
65 #include <stdint.h>
66 #include <stdbool.h>
67 
68 /**
69  * @defgroup MLMR_C_MACRO Defines
70  * @{
71  */
72 #define MLMR_C_CONNECTION_MAX 10 /**< Maximum number of MLMR Client connections. */
73 
74 /**
75  * @defgroup MLMR_C_UUID Service and Characteristics UUID
76  * @{
77  */
78 #define MLMR_C_SVC_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
79  0x0A, 0x46, 0x44, 0xD3, 0x01, 0x02, 0xED, 0xA6} /**< UUID of MLMR_C Service. */
80 #define MLMR_C_TX_CHAR_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
81  0x0A, 0x46, 0x44, 0xD3, 0x02, 0x02, 0xED, 0xA6} /**< UUID of MLMR_C Tx characterisitc. */
82 #define MLMR_C_RX_CHAR_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
83  0x0A, 0x46, 0x44, 0xD3, 0x03, 0x02, 0xED, 0xA6} /**< UUID of MLMR_C Rx characterisitc. */
84 #define MLMR_C_FLOW_CTRL_UUID {0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
85  0x0A, 0x46, 0x44, 0xD3, 0x04, 0x02, 0xED, 0xA6} /**< UUID of MLMR_C Flow Control characterisitc. */
86 /** @} */
87 /** @} */
88 
89 /**
90  * @defgroup MLMR_C_ENUM Enumerations
91  * @{
92  */
93 /**@brief Multi Link Multi Role Service Client event type. */
94 typedef enum
95 {
96  MLMR_C_EVT_INVALID, /**< Invalid MLMR Client event. */
97  MLMR_C_EVT_DISCOVERY_COMPLETE, /**< MLMR Client has found service and its characteristics at peer. */
98  MLMR_C_EVT_DISCOVERY_FAIL, /**< MLMR Client found the service failed because of invalid operation or no found at peer. */
99  MLMR_C_EVT_TX_NTF_SET_SUCCESS, /**< MLMR Client has set peer Tx notify. */
100  MLMR_C_EVT_FLOW_CTRL_NTF_SET_SUCCESS, /**< MLMR Client has set peer ble flow control notify. */
101  MLMR_C_EVT_PEER_DATA_RECEIVE, /**< MLMR Client has received something from peer. */
102  MLMR_C_EVT_TX_CPLT, /**< MLMR Client has sent something to peer successfully. */
103  MLMR_C_EVT_TX_FLOW_OFF, /**< MLMR Client has received Tx flow off control request from peer. */
104  MLMR_C_EVT_TX_FLOW_ON, /**< MLMR Client has received Tx flow on control request from peer. */
105  MLMR_C_EVT_RX_FLOW_UPDATE_CPLT, /**< MLMR CLient has updated flow control to peer completely. */
106  MLMR_C_EVT_WRITE_OP_ERR, /**< Error occured when MLMR Client wrote to peer. */
108 
109 /**@brief Flow control state for MLMR Client service. */
111 {
112  MLMR_C_FLOW_CTRL_STATE_OFF = 0, /**< Indicate that MLMR Client can not receive data from peer. */
113  MLMR_C_FLOW_CTRL_STATE_ON /**< Indicate that MLMR Client can receive data from peer. */
114 };
115 /**@brief Underlying type used for the MLMR Client flow control state. */
116 typedef uint8_t mlmr_c_flow_ctrl_state_t;
117 /** @} */
118 
119 /**
120  * @defgroup MLMR_C_STRUCT Structures
121  * @{
122  */
123 /**@brief Handles on the connected peer device needed to interact with it. */
124 typedef struct
125 {
126  uint16_t mlmr_c_srvc_start_handle; /**< MLMR_C Service start handle. */
127  uint16_t mlmr_c_srvc_end_handle; /**< MLMR_C Service end handle. */
128  uint16_t mlmr_c_tx_handle; /**< Handle of MLMR_C Tx characteristic as provided by a discovery. */
129  uint16_t mlmr_c_tx_cccd_handle; /**< Handle of CCCD of MLMR_C Tx characteristic as provided by a discovery. */
130  uint16_t mlmr_c_rx_handle; /**< Handle of MLMR_C Rx characteristic as provided by a discovery. */
131  uint16_t mlmr_c_flow_ctrl_handle; /**< Handle of MLMR_C Flow Control characteristic as provided by a discovery. */
132  uint16_t mlmr_c_flow_ctrl_cccd_handle; /**< Handle of CCCD of MLMR_C Flow Control characteristic as provided by a discovery. */
134 
135 /**@brief Multi Link Multi Role Service Client event. */
136 typedef struct
137 {
138  uint8_t conn_idx; /**< Connection index. */
139  mlmr_c_evt_type_t evt_type; /**< MLMR Client event type. */
140  uint16_t length; /**< Length of event data. */
141  uint8_t *p_data; /**< Pointer to event data. */
142 } mlmr_c_evt_t;
143 /** @} */
144 
145 /**
146  * @defgroup MLMR_C_TYPEDEF Typedefs
147  * @{
148  */
149 /**@brief Multi Link Multi Role Service Client event handler type. */
150 typedef void (* mlmr_c_evt_handler_t)(mlmr_c_evt_t *p_evt);
151 /** @} */
152 
153 /**
154  * @defgroup MLMR_C_FUNCTION Functions
155  * @{
156  */
157 /**
158  *****************************************************************************************
159  * @brief Register MLMR Client event handler.
160  *
161  * @param[in] evt_handler: Multi Link Multi Role Service Client event handler.
162  *
163  * @return Result of initialization.
164  *****************************************************************************************
165  */
167 
168 /**
169  *****************************************************************************************
170  * @brief Discovery MLMR_C on peer.
171  *
172  * @param[in] conn_idx: Index of connection.
173  *
174  * @return Operation result.
175  *****************************************************************************************
176  */
178 
179 /**
180  *****************************************************************************************
181  * @brief Enable or disable peer MLMR_C Tx characteristic notify.
182  *
183  * @param[in] conn_idx: Connection index.
184  * @param[in] is_enable: Enable or disable ths Tx notify.
185  *
186  * @return Operation result.
187  *****************************************************************************************
188  */
189 sdk_err_t mlmr_c_tx_notify_set(uint8_t conn_idx, bool is_enable);
190 
191 /**
192  *****************************************************************************************
193  * @brief Enable or disable peer device MLMR_C flow control notify.
194  *
195  * @param[in] conn_idx: Connection index.
196  * @param[in] is_enable: Enable or disable ths Tx notify.
197  *
198  * @return Operation result.
199  *****************************************************************************************
200  */
201 sdk_err_t mlmr_c_flow_ctrl_notify_set(uint8_t conn_idx, bool is_enable);
202 
203 /**
204  *****************************************************************************************
205  * @brief Send data to the server.
206  *
207  * @param[in] conn_idx: Connection index.
208  * @param[in] p_data: Pointer to data need sent.
209  * @param[in] length: Length of data need sent.
210  *
211  * @return Operation result.
212  *****************************************************************************************
213  */
214 sdk_err_t mlmr_c_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
215 
216 /**
217  *****************************************************************************************
218  * @brief Send MLMR Client Rx flow control state to peer device
219  *
220  * @param[in] conn_idx: Connection index.
221  * @param[in] flow_ctrl: MLMR client Rx flow control state.
222  *
223  * @return Result of sending mlmr_c Rx flow control state.
224  *****************************************************************************************
225  */
227 /** @} */
228 #endif
229 /** @} */
230 /** @} */
231 
MLMR_C_FLOW_CTRL_STATE_ON
@ MLMR_C_FLOW_CTRL_STATE_ON
Indicate that MLMR Client can receive data from peer.
Definition: mlmr_c.h:113
mlmr_c_handles_t::mlmr_c_tx_cccd_handle
uint16_t mlmr_c_tx_cccd_handle
Handle of CCCD of MLMR_C Tx characteristic as provided by a discovery.
Definition: mlmr_c.h:129
mlmr_c_handles_t::mlmr_c_flow_ctrl_handle
uint16_t mlmr_c_flow_ctrl_handle
Handle of MLMR_C Flow Control characteristic as provided by a discovery.
Definition: mlmr_c.h:131
mlmr_c_evt_t
Multi Link Multi Role Service Client event.
Definition: mlmr_c.h:137
MLMR_C_EVT_DISCOVERY_FAIL
@ MLMR_C_EVT_DISCOVERY_FAIL
MLMR Client found the service failed because of invalid operation or no found at peer.
Definition: mlmr_c.h:98
mlmr_c_handles_t::mlmr_c_flow_ctrl_cccd_handle
uint16_t mlmr_c_flow_ctrl_cccd_handle
Handle of CCCD of MLMR_C Flow Control characteristic as provided by a discovery.
Definition: mlmr_c.h:132
MLMR_C_EVT_FLOW_CTRL_NTF_SET_SUCCESS
@ MLMR_C_EVT_FLOW_CTRL_NTF_SET_SUCCESS
MLMR Client has set peer ble flow control notify.
Definition: mlmr_c.h:100
gr_includes.h
Include Files API.
mlmr_c_evt_type_t
mlmr_c_evt_type_t
Multi Link Multi Role Service Client event type.
Definition: mlmr_c.h:95
mlmr_c_flow_ctrl_state_t
uint8_t mlmr_c_flow_ctrl_state_t
Underlying type used for the MLMR Client flow control state.
Definition: mlmr_c.h:116
mlmr_c_evt_handler_t
void(* mlmr_c_evt_handler_t)(mlmr_c_evt_t *p_evt)
Multi Link Multi Role Service Client event handler type.
Definition: mlmr_c.h:150
mlmr_c_handles_t::mlmr_c_tx_handle
uint16_t mlmr_c_tx_handle
Handle of MLMR_C Tx characteristic as provided by a discovery.
Definition: mlmr_c.h:128
mlmr_c_evt_t::evt_type
mlmr_c_evt_type_t evt_type
MLMR Client event type.
Definition: mlmr_c.h:139
MLMR_C_EVT_TX_FLOW_OFF
@ MLMR_C_EVT_TX_FLOW_OFF
MLMR Client has received Tx flow off control request from peer.
Definition: mlmr_c.h:103
MLMR_C_EVT_TX_FLOW_ON
@ MLMR_C_EVT_TX_FLOW_ON
MLMR Client has received Tx flow on control request from peer.
Definition: mlmr_c.h:104
mlmr_client_init
sdk_err_t mlmr_client_init(mlmr_c_evt_handler_t evt_handler)
Register MLMR Client event handler.
MLMR_C_EVT_TX_NTF_SET_SUCCESS
@ MLMR_C_EVT_TX_NTF_SET_SUCCESS
MLMR Client has set peer Tx notify.
Definition: mlmr_c.h:99
mlmr_c_rx_flow_ctrl_set
sdk_err_t mlmr_c_rx_flow_ctrl_set(uint8_t conn_idx, mlmr_c_flow_ctrl_state_t flow_ctrl)
Send MLMR Client Rx flow control state to peer device.
MLMR_C_EVT_PEER_DATA_RECEIVE
@ MLMR_C_EVT_PEER_DATA_RECEIVE
MLMR Client has received something from peer.
Definition: mlmr_c.h:101
mlmr_c_handles_t
Handles on the connected peer device needed to interact with it.
Definition: mlmr_c.h:125
mlmr_c_tx_notify_set
sdk_err_t mlmr_c_tx_notify_set(uint8_t conn_idx, bool is_enable)
Enable or disable peer MLMR_C Tx characteristic notify.
MLMR_C_EVT_INVALID
@ MLMR_C_EVT_INVALID
Invalid MLMR Client event.
Definition: mlmr_c.h:96
mlmr_c_flow_ctrl_state
mlmr_c_flow_ctrl_state
Flow control state for MLMR Client service.
Definition: mlmr_c.h:111
mlmr_c_handles_t::mlmr_c_rx_handle
uint16_t mlmr_c_rx_handle
Handle of MLMR_C Rx characteristic as provided by a discovery.
Definition: mlmr_c.h:130
MLMR_C_EVT_DISCOVERY_COMPLETE
@ MLMR_C_EVT_DISCOVERY_COMPLETE
MLMR Client has found service and its characteristics at peer.
Definition: mlmr_c.h:97
ble_prf_types.h
Profile/Service Common Types.
mlmr_c_tx_data_send
sdk_err_t mlmr_c_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length)
Send data to the server.
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
mlmr_c_evt_t::length
uint16_t length
Length of event data.
Definition: mlmr_c.h:140
mlmr_c_handles_t::mlmr_c_srvc_start_handle
uint16_t mlmr_c_srvc_start_handle
MLMR_C Service start handle.
Definition: mlmr_c.h:126
mlmr_c_flow_ctrl_notify_set
sdk_err_t mlmr_c_flow_ctrl_notify_set(uint8_t conn_idx, bool is_enable)
Enable or disable peer device MLMR_C flow control notify.
mlmr_c_evt_t::p_data
uint8_t * p_data
Pointer to event data.
Definition: mlmr_c.h:141
MLMR_C_EVT_TX_CPLT
@ MLMR_C_EVT_TX_CPLT
MLMR Client has sent something to peer successfully.
Definition: mlmr_c.h:102
MLMR_C_FLOW_CTRL_STATE_OFF
@ MLMR_C_FLOW_CTRL_STATE_OFF
Indicate that MLMR Client can not receive data from peer.
Definition: mlmr_c.h:112
MLMR_C_EVT_RX_FLOW_UPDATE_CPLT
@ MLMR_C_EVT_RX_FLOW_UPDATE_CPLT
MLMR CLient has updated flow control to peer completely.
Definition: mlmr_c.h:105
MLMR_C_EVT_WRITE_OP_ERR
@ MLMR_C_EVT_WRITE_OP_ERR
Error occured when MLMR Client wrote to peer.
Definition: mlmr_c.h:106
mlmr_c_disc_srvc_start
sdk_err_t mlmr_c_disc_srvc_start(uint8_t conn_idx)
Discovery MLMR_C on peer.
mlmr_c_evt_t::conn_idx
uint8_t conn_idx
Connection index.
Definition: mlmr_c.h:138
mlmr_c_handles_t::mlmr_c_srvc_end_handle
uint16_t mlmr_c_srvc_end_handle
MLMR_C Service end handle.
Definition: mlmr_c.h:127