1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
/**
******************************************************************************
* @file svc_ctl.h
* @author MCD Application Team
* @brief Header for ble_controller.c module
******************************************************************************
* @attention
*
* Copyright (c) 2018-2021 STMicroelectronics.
* All rights reserved.
*
* This software is licensed under terms that can be found in the LICENSE file
* in the root directory of this software component.
* If no LICENSE file comes with this software, it is provided AS-IS.
*
******************************************************************************
*/
/**
* The BLE Controller supports the application to handle services and clients.
* It provides an API to initialize the BLE core Device and a handler mechanism to rout the GATT/GAP events to the
* application. When the ble_controller is used (recommended), the application shall register a callback for each
* Service and each Client implemented. This is already done with the Services and Clients provided in that delivery.
* + A GATT event is relevant to only one Service and/or one Client. When a GATT event is received, it is notified to
* the registered handlers to the BLE controller. When no registered handler acknowledges positively the GATT event,
* it is reported to the application.
* + A GAP event is not relevant to either a Service or a Client. It is sent to the application
* + In case the application does not want to take benefit from the ble_controller, it could bypass it. In that case,
* the application shall:
* - call SVCCTL_Init() to initialize the BLE core device (or implement on its own what is inside that function
* - implement TLHCI_UserEvtRx() which is the notification from the HCI layer to report all events (GATT/GAP).
*/
/* Define to prevent recursive inclusion -------------------------------------*/
#ifndef __SVCCTL_H
#define __SVCCTL_H
#ifdef __cplusplus
extern "C" {
#endif
/* Includes ------------------------------------------------------------------*/
/* Exported types ------------------------------------------------------------*/
typedef enum
{
SVCCTL_EvtNotAck,
SVCCTL_EvtAckFlowEnable,
SVCCTL_EvtAckFlowDisable,
} SVCCTL_EvtAckStatus_t;
typedef enum
{
SVCCTL_UserEvtFlowDisable,
SVCCTL_UserEvtFlowEnable,
} SVCCTL_UserEvtFlowStatus_t;
typedef SVCCTL_EvtAckStatus_t (*SVC_CTL_p_EvtHandler_t)(void *p_evt);
/* Exported constants --------------------------------------------------------*/
/* External variables --------------------------------------------------------*/
/* Exported macros -----------------------------------------------------------*/
/* Exported functions ------------------------------------------------------- */
/**
* @brief It initializes the BLE core Driver and sends some commands to initialize the BLE core device
* It shall be called before any BLE operation
*
* @param None
* @retval None
*/
void SVCCTL_Init( void );
/**
* @brief This API registers a handler to be called when a GATT user event is received from the BLE core device. When
* a Service is created, it shall register a callback to be notified when a GATT event is received from the
* BLE core device. When a GATT event is received, it shall be checked in the handler if the GATT events belongs
* to the Service or not. The handler shall return the correct status depending on the result. As soon as one
* Service handler registered acknowledges positively the GATT event, the ble_controller stops calling the
* registered Service handlers.
* This handler is called in the TL_BLE_HCI_UserEvtProc() context
*
* @param pfBLE_SVC_Service_Event_Handler: This is the Service handler that the ble_controller calls to report a GATT
* event received. If the GATT event belongs to that Service, the callback shall return positively with
* SVCCTL_EvtAckFlowEnable.
* @retval None
*/
void SVCCTL_RegisterSvcHandler( SVC_CTL_p_EvtHandler_t pfBLE_SVC_Service_Event_Handler );
/**
* @brief This API registers a handler to be called when a GATT user event is received from the BLE core device. When
* a Client is created, it shall register a callback to be notified when a GATT event is received from the
* BLE core device. When a GATT event is received, it shall be checked in the handler if the GATT events belongs
* to the Client or not. The handler shall return the correct status depending on the result. As soon as one
* Client handler registered acknowledges positively the GATT event, the ble_controller stops calling the
* registered Client handlers.
* This handler is called in the TL_BLE_HCI_UserEvtProc() context
*
* @param pfBLE_SVC_Client_Event_Handler: This is the Client handler that the ble_controller calls to report a GATT
* event received. If the GATT event belongs to that Client, the callback shall return positively with
* SVCCTL_EvtAckFlowEnable.
* @retval None
*/
void SVCCTL_RegisterCltHandler( SVC_CTL_p_EvtHandler_t pfBLE_SVC_Client_Event_Handler );
/**
* @brief This API is used to resume the User Event Flow that has been stopped in return of SVCCTL_UserEvtRx()
*
* @param None
* @retval None
*/
void SVCCTL_ResumeUserEventFlow( void );
/**
* @brief This callback is triggered when either
* + a GAP event is received from the BLE core device.
* + a GATT event that has not been positively acknowledged by the registered handler is received from the
* BLE core device.
* The event is returned in a HCI packet. The full HCI packet is stored in a single buffer and is available when
* this callback is triggered. However, an ACI event may be longer than a HCI packet and could be fragmented over
* several HCI packets. The HCI layer only handles HCI packets so when an ACI packet is split over several HCI
* packets, this callback is triggered for each HCI fragment. It is the responsibility of the application to
* reassemble the ACI event.
* This callback is triggered in the TL_BLE_HCI_UserEvtProc() context
*
* @param pckt: The user event received from the BLE core device
* @retval None
*/
SVCCTL_UserEvtFlowStatus_t SVCCTL_App_Notification( void *pckt );
/**
* @brief
*
*
* @param pckt: The user event received from the BLE core device
* @retval SVCCTL_UserEvtFlowStatus_t: SVCCTL_UserEvtFlowEnable when the packet has been processed
* SVCCTL_UserEvtFlowDisable otherwise (the packet is kept in the queue)
*/
SVCCTL_UserEvtFlowStatus_t SVCCTL_UserEvtRx( void *pckt );
/**
* @brief This API may be used by the application when the Service Controller is used to add a custom service
*
*
* @param None
* @retval None
*/
void SVCCTL_InitCustomSvc( void );
/**
* @brief This API may be overloaded by the application to select a limited list of ble services to initialize.
* It is called by SVCCTL_Init()
* By default, SVCCTL_SvcInit() is implemented to initialize all BLE services which are included in the
* application at build time
* If it is required to initialize only limited part of the BLE service available in the application,
* this API may be used to call the initialization API of the subset of needed services at run time.
*
* @param None
* @retval None
*/
void SVCCTL_SvcInit( void );
#ifdef __cplusplus
}
#endif
#endif /*__SVCCTL_H */
|
