tps_c.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file tps_c.h
5 *
6 * @brief Tx Power Service Client API
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 */
42
43 /**
44 * @defgroup BLE_SDK_TPS_C Tx Power Service Client (TPS_C)
45 * @{
46 * @brief Tx Power Service Client module.
47 *
48 * @details The Tx Power Service Client contains the APIs and types, which can be used by the
49 * application to discovery of Tx Power Service of peer and interact with it.
50 *
51 * The application must provide an event handler to register, then call \ref tps_client_init().
52 * After Tx Power Service Client discoveries peer Tx Power Service, application can call
53 * \ref tps_c_tx_power_level_read() to get tx power data from peer.
54 */
55
56 #ifndef __TPS_C_H__
57 #define __TPS_C_H__
58
59 #include "gr_includes.h"
60 #include "ble_prf_types.h"
61 #include "custom_config.h"
62 #include <stdint.h>
63 #include <stdbool.h>
64
65 /**
66 * @defgroup TPS_C_MACRO Defines
67 * @{
68 */
69 #define TPS_C_CONNECTION_MAX 10 /**< Maximum number of TPS Client connections. */
70 /** @} */
71
72 /**
73 * @defgroup TPS_C_ENUM Enumerations
74 * @{
75 */
76 /**@brief Tx Power Service Client event type. */
77 typedef enum
78 {
79 TPS_C_EVT_INVALID, /**< TPS Client invalid event. */
80 TPS_C_EVT_DISCOVERY_COMPLETE, /**< TPS Client has found TPS service and its characteristics. */
81 TPS_C_EVT_DISCOVERY_FAIL, /**< TPS Client found TPS service failed because of invalid operation or no found at the peer. */
82 TPS_C_EVT_TX_POWER_LEVEL_RECEIVE, /**< TPS Client has received Tx Power Level value. */
83 } tps_c_evt_type_t;
84 /** @} */
85
86 /**
87 * @defgroup TPS_C_STRUCT Structures
88 * @{
89 */
90 /**@brief Handles on the connected peer device needed to interact with it. */
91 typedef struct
92 {
93 uint16_t tps_srvc_start_handle; /**< TPS Service start handle. */
94 uint16_t tps_srvc_end_handle; /**< TPS Service end handle. */
95 uint16_t tps_tx_power_level_handle; /**< TPS Tx Power Level characteristic Value handle which has been got from peer. */
96 } tps_c_handles_t;
97
98 /**@brief Tx Power Service Client event. */
99 typedef struct
100 {
101 uint8_t conn_idx; /**< The connection index. */
102 tps_c_evt_type_t evt_type; /**< TPS Client event type. */
103 int8_t tx_power_level; /**< Tx Power level. */
104 } tps_c_evt_t;
105 /** @} */
106
107 /**
108 * @defgroup TPS_C_TYPEDEF Typedefs
109 * @{
110 */
111 /**@brief Tx Power Service Client event handler type. */
112 typedef void (*tps_c_evt_handler_t)(tps_c_evt_t *p_evt);
113 /** @} */
114
115 /**
116 * @defgroup TPS_C_FUNCTION Functions
117 * @{
118 */
119 /**
120 *****************************************************************************************
121 * @brief Register TPS Client event handler.
122 *
123 * @param[in] evt_handler: Tx Power Service Client event handler.
124 *
125 * @return Result of initialization.
126 *****************************************************************************************
127 */
128 sdk_err_t tps_client_init(tps_c_evt_handler_t evt_handler);
129
130 /**
131 *****************************************************************************************
132 * @brief Discovery Tx Power Service on peer.
133 *
134 * @param[in] conn_idx: Index of connection.
135 *
136 * @return Operation result.
137 *****************************************************************************************
138 */
139 sdk_err_t tps_c_disc_srvc_start(uint8_t conn_idx);
140
141 /**
142 *****************************************************************************************
143 * @brief Read Tx Power Level characteristic value.
144 *
145 * @param[in] conn_idx: Index of connection.
146 *
147 * @return Operation result.
148 *****************************************************************************************
149 */
150 sdk_err_t tps_c_tx_power_level_read(uint8_t conn_idx);
151 /** @} */
152
153 #endif
154 /** @} */
155 /** @} */
tps_c_handles_t::tps_srvc_end_handle
uint16_t tps_srvc_end_handle
TPS Service end handle.
Definition: tps_c.h:94
tps_c_evt_handler_t
void(* tps_c_evt_handler_t)(tps_c_evt_t *p_evt)
Tx Power Service Client event handler type.
Definition: tps_c.h:112
tps_c_handles_t::tps_srvc_start_handle
uint16_t tps_srvc_start_handle
TPS Service start handle.
Definition: tps_c.h:93
gr_includes.h
Include Files API.
tps_c_evt_type_t
tps_c_evt_type_t
Tx Power Service Client event type.
Definition: tps_c.h:78
TPS_C_EVT_TX_POWER_LEVEL_RECEIVE
@ TPS_C_EVT_TX_POWER_LEVEL_RECEIVE
TPS Client has received Tx Power Level value.
Definition: tps_c.h:82
tps_client_init
sdk_err_t tps_client_init(tps_c_evt_handler_t evt_handler)
Register TPS Client event handler.
tps_c_evt_t
Tx Power Service Client event.
Definition: tps_c.h:100
tps_c_tx_power_level_read
sdk_err_t tps_c_tx_power_level_read(uint8_t conn_idx)
Read Tx Power Level characteristic value.
ble_prf_types.h
Profile/Service Common Types.
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
tps_c_evt_t::conn_idx
uint8_t conn_idx
The connection index.
Definition: tps_c.h:101
TPS_C_EVT_DISCOVERY_COMPLETE
@ TPS_C_EVT_DISCOVERY_COMPLETE
TPS Client has found TPS service and its characteristics.
Definition: tps_c.h:80
tps_c_handles_t
Handles on the connected peer device needed to interact with it.
Definition: tps_c.h:92
tps_c_handles_t::tps_tx_power_level_handle
uint16_t tps_tx_power_level_handle
TPS Tx Power Level characteristic Value handle which has been got from peer.
Definition: tps_c.h:95
tps_c_evt_t::tx_power_level
int8_t tx_power_level
Tx Power level.
Definition: tps_c.h:103
tps_c_evt_t::evt_type
tps_c_evt_type_t evt_type
TPS Client event type.
Definition: tps_c.h:102
tps_c_disc_srvc_start
sdk_err_t tps_c_disc_srvc_start(uint8_t conn_idx)
Discovery Tx Power Service on peer.
TPS_C_EVT_INVALID
@ TPS_C_EVT_INVALID
TPS Client invalid event.
Definition: tps_c.h:79
TPS_C_EVT_DISCOVERY_FAIL
@ TPS_C_EVT_DISCOVERY_FAIL
TPS Client found TPS service failed because of invalid operation or no found at the peer.
Definition: tps_c.h:81