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. */
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. */
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  */
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  */
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  */
151 /** @} */
152 
153 #endif
154 /** @} */
155 /** @} */
tps_c_handles_t::tps_srvc_end_handle
uint16_t tps_srvc_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
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
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:290
tps_c_evt_t::conn_idx
uint8_t conn_idx
Definition: tps_c.h:101
TPS_C_EVT_DISCOVERY_COMPLETE
@ TPS_C_EVT_DISCOVERY_COMPLETE
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
Definition: tps_c.h:95
tps_c_evt_t::tx_power_level
int8_t tx_power_level
Definition: tps_c.h:103
tps_c_evt_t::evt_type
tps_c_evt_type_t evt_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
Definition: tps_c.h:79
TPS_C_EVT_DISCOVERY_FAIL
@ TPS_C_EVT_DISCOVERY_FAIL
Definition: tps_c.h:81