libnx  v4.2.2
btmu.h
Go to the documentation of this file.
1 /**
2  * @file btmu.h
3  * @brief btm:u (btm user) service IPC wrapper.
4  * @note Only available on [5.0.0+].
5  * @note See also btdev.
6  * @note See also: https://switchbrew.org/wiki/BTM_services
7  * @author yellows8
8  */
9 #pragma once
10 #include "../types.h"
11 #include "../kernel/event.h"
12 #include "../services/btdrv_types.h"
13 #include "../services/btm.h"
14 #include "../sf/service.h"
15 
16 /// Initialize btm:u.
18 
19 /// Exit btm:u.
20 void btmuExit(void);
21 
22 /// Gets the Service object for the actual btm:u service session. This object must be closed by the user once finished using cmds with this.
24 
25 /// Gets the Service object for IBtmUserCore.
27 
28 /**
29  * @brief AcquireBleScanEvent
30  * @note This is similar to \ref btmAcquireBleScanEvent.
31  * @note The Event must be closed by the user once finished with it.
32  * @param[out] out_event Output Event with autoclear=true.
33  */
35 
36 /**
37  * @brief GetBleScanFilterParameter
38  * @note This is the same as \ref btmGetBleScanParameterGeneral.
39  * @param[in] parameter_id Must be value 0x1 or 0xFFFF.
40  * @param[out] out \ref BtdrvBleAdvertisePacketParameter
41  */
43 
44 /**
45  * @brief GetBleScanFilterParameter2
46  * @note This is the same as \ref btmGetBleScanParameterSmartDevice.
47  * @param[in] parameter_id Must be value 0x2.
48  * @param[out] out \ref BtdrvGattAttributeUuid. The first 4-bytes is always 0.
49  */
51 
52 /**
53  * @brief StartBleScanForGeneral
54  * @note This is similar to \ref btmStartBleScanForGeneral.
55  * @param[in] param \ref BtdrvBleAdvertisePacketParameter
56  */
58 
59 /**
60  * @brief StopBleScanForGeneral
61  * @note This is similar to \ref btmStopBleScanForGeneral.
62  */
64 
65 /**
66  * @brief GetBleScanResultsForGeneral
67  * @note This is similar to \ref btmGetBleScanResultsForGeneral.
68  * @param[out] results Output array of \ref BtdrvBleScanResult.
69  * @param[in] count Size of the results array in entries. The max is 10.
70  * @param[out] total_out Total output entries.
71  */
73 
74 /**
75  * @brief StartBleScanForPaired
76  * @note This is similar to \ref btmStartBleScanForPaired.
77  * @param[in] param \ref BtdrvBleAdvertisePacketParameter
78  */
80 
81 /**
82  * @brief StopBleScanForPaired
83  * @note This is similar to \ref btmStopBleScanForPaired.
84  */
86 
87 /**
88  * @brief StartBleScanForSmartDevice
89  * @note This is similar to \ref btmStartBleScanForSmartDevice.
90  * @param[in] uuid \ref BtdrvGattAttributeUuid
91  */
93 
94 /**
95  * @brief StopBleScanForSmartDevice
96  * @note This is similar to \ref btmStopBleScanForSmartDevice.
97  */
99 
100 /**
101  * @brief GetBleScanResultsForSmartDevice
102  * @note This is similar to \ref btmGetBleScanResultsForSmartDevice.
103  * @param[out] results Output array of \ref BtdrvBleScanResult.
104  * @param[in] count Size of the results array in entries. The max is 10.
105  * @param[out] total_out Total output entries.
106  */
108 
109 /**
110  * @brief AcquireBleConnectionEvent
111  * @note This is similar to \ref btmAcquireBleConnectionEvent.
112  * @note The Event must be closed by the user once finished with it.
113  * @param[out] out_event Output Event with autoclear=true.
114  */
116 
117 /**
118  * @brief BleConnect
119  * @note This is similar to \ref btmBleConnect.
120  * @param[in] addr \ref BtdrvAddress
121  */
123 
124 /**
125  * @brief BleDisconnect
126  * @note This is similar to \ref btmBleDisconnect.
127  * @param[in] connection_handle This must match a BtdrvBleConnectionInfo::connection_handle from \ref btmuBleGetConnectionState. [5.1.0+] 0xFFFFFFFF is invalid.
128  */
129 Result btmuBleDisconnect(u32 connection_handle);
130 
131 /**
132  * @brief BleGetConnectionState
133  * @note This is similar to \ref btmBleGetConnectionState.
134  * @param[out] info Output array of \ref BtdrvBleConnectionInfo.
135  * @param[in] count Size of the info array in entries. Other cmds which use this internally use count=4.
136  * @param[out] total_out Total output entries.
137  */
139 
140 /**
141  * @brief AcquireBlePairingEvent
142  * @note This is similar to \ref btmAcquireBlePairingEvent.
143  * @note The Event must be closed by the user once finished with it.
144  * @param[out] out_event Output Event with autoclear=true.
145  */
147 
148 /**
149  * @brief BlePairDevice
150  * @note This is similar to \ref btmBlePairDevice.
151  * @param[in] connection_handle Same as \ref btmuBleDisconnect.
152  * @param[in] param \ref BtdrvBleAdvertisePacketParameter
153  */
155 
156 /**
157  * @brief BleUnPairDevice
158  * @note This is similar to \ref btmBleUnpairDeviceOnBoth.
159  * @param[in] connection_handle Same as \ref btmuBleDisconnect.
160  * @param[in] param \ref BtdrvBleAdvertisePacketParameter
161  */
163 
164 /**
165  * @brief BleUnPairDevice2
166  * @note This is similar to \ref btmBleUnPairDevice.
167  * @param[in] addr \ref BtdrvAddress
168  * @param[in] param \ref BtdrvBleAdvertisePacketParameter
169  */
171 
172 /**
173  * @brief BleGetPairedDevices
174  * @note This is similar to \ref btmBleGetPairedAddresses.
175  * @param[in] param \ref BtdrvBleAdvertisePacketParameter
176  * @param[out] addrs Output array of \ref BtdrvAddress.
177  * @param[in] count Size of the addrs array in entries.
178  * @param[out] total_out Total output entries. The max is 10.
179  */
181 
182 /**
183  * @brief AcquireBleServiceDiscoveryEvent
184  * @note This is similar to \ref btmAcquireBleServiceDiscoveryEvent.
185  * @note The Event must be closed by the user once finished with it.
186  * @param[out] out_event Output Event with autoclear=true.
187  */
189 
190 /**
191  * @brief GetGattServices
192  * @note This is similar to \ref btmGetGattServices.
193  * @param[in] connection_handle Same as \ref btmuBleDisconnect.
194  * @param[out] services Output array of \ref BtmGattService.
195  * @param[in] count Size of the services array in entries. The max is 100.
196  * @param[out] total_out Total output entries.
197  */
198 Result btmuGetGattServices(u32 connection_handle, BtmGattService *services, u8 count, u8 *total_out);
199 
200 /**
201  * @brief Same as \ref btmuGetGattServices except this only returns the \ref BtmGattService which matches the input \ref BtdrvGattAttributeUuid.
202  * @note This is similar to \ref btmGetGattService.
203  * @param[in] connection_handle Same as \ref btmuBleDisconnect.
204  * @param[in] uuid \ref BtdrvGattAttributeUuid
205  * @param[out] service \ref BtmGattService
206  * @param[out] flag Whether a \ref BtmGattService was returned.
207  */
208 Result btmuGetGattService(u32 connection_handle, const BtdrvGattAttributeUuid *uuid, BtmGattService *service, bool *flag);
209 
210 /**
211  * @brief Same as \ref btmuGetGattServices except this only returns \ref BtmGattService entries where various checks pass with u16 fields.
212  * @note This is similar to \ref btmGetGattIncludedServices.
213  * @param[in] connection_handle Same as \ref btmuBleDisconnect.
214  * @param[in] service_handle ServiceHandle
215  * @param[out] services \ref BtmGattService
216  * @param[in] count Size of the services array in entries. The max is 100.
217  * @param[out] out Output value.
218  */
219 Result btmuGetGattIncludedServices(u32 connection_handle, u16 service_handle, BtmGattService *services, u8 count, u8 *out);
220 
221 /**
222  * @brief This is similar to \ref btmuGetGattIncludedServices except this only returns 1 \ref BtmGattService.
223  * @note This is similar to \ref btmGetBelongingService.
224  * @param[in] connection_handle Same as \ref btmuBleDisconnect.
225  * @param[in] attribute_handle AttributeHandle
226  * @param[out] service \ref BtmGattService
227  * @param[out] flag Whether a \ref BtmGattService was returned.
228  */
229 Result btmuGetBelongingGattService(u32 connection_handle, u16 attribute_handle, BtmGattService *service, bool *flag);
230 
231 /**
232  * @brief GetGattCharacteristics
233  * @note This is similar to \ref btmGetGattCharacteristics.
234  * @param[in] connection_handle Same as \ref btmuBleDisconnect.
235  * @param[in] service_handle This controls which \ref BtmGattCharacteristic entries to return.
236  * @param[out] characteristics \ref BtmGattCharacteristic
237  * @param[in] count Size of the characteristics array in entries. The max is 100.
238  * @param[out] total_out Total output entries.
239  */
240 Result btmuGetGattCharacteristics(u32 connection_handle, u16 service_handle, BtmGattCharacteristic *characteristics, u8 count, u8 *total_out);
241 
242 /**
243  * @brief GetGattDescriptors
244  * @note This is similar to \ref btmGetGattDescriptors.
245  * @param[in] connection_handle Same as \ref btmuBleDisconnect.
246  * @param[in] char_handle Characteristic handle. This controls which \ref BtmGattDescriptor entries to return.
247  * @param[out] descriptors \ref BtmGattDescriptor
248  * @param[in] count Size of the descriptors array in entries. The max is 100.
249  * @param[out] total_out Total output entries.
250  */
251 Result btmuGetGattDescriptors(u32 connection_handle, u16 char_handle, BtmGattDescriptor *descriptors, u8 count, u8 *total_out);
252 
253 /**
254  * @brief AcquireBleMtuConfigEvent
255  * @note This is similar to \ref btmAcquireBleMtuConfigEvent.
256  * @note The Event must be closed by the user once finished with it.
257  * @param[out] out_event Output Event with autoclear=true.
258  */
260 
261 /**
262  * @brief ConfigureBleMtu
263  * @note This is similar to \ref btmConfigureBleMtu.
264  * @param[in] connection_handle Same as \ref btmuBleDisconnect.
265  * @param[in] mtu MTU
266  */
267 Result btmuConfigureBleMtu(u32 connection_handle, u16 mtu);
268 
269 /**
270  * @brief GetBleMtu
271  * @note This is similar to \ref btmGetBleMtu.
272  * @param[in] connection_handle Same as \ref btmuBleDisconnect.
273  * @param[out] out Output MTU.
274  */
275 Result btmuGetBleMtu(u32 connection_handle, u16 *out);
276 
277 /**
278  * @brief RegisterBleGattDataPath
279  * @note This is similar to \ref btmRegisterBleGattDataPath.
280  * @param[in] path \ref BtmBleDataPath
281  */
283 
284 /**
285  * @brief UnregisterBleGattDataPath
286  * @note This is similar to \ref btmUnregisterBleGattDataPath.
287  * @param[in] path \ref BtmBleDataPath
288  */
290 
btmuAcquireBleServiceDiscoveryEvent
Result btmuAcquireBleServiceDiscoveryEvent(Event *out_event)
AcquireBleServiceDiscoveryEvent.
btmuRegisterBleGattDataPath
Result btmuRegisterBleGattDataPath(const BtmBleDataPath *path)
RegisterBleGattDataPath.
btmuGetGattDescriptors
Result btmuGetGattDescriptors(u32 connection_handle, u16 char_handle, BtmGattDescriptor *descriptors, u8 count, u8 *total_out)
GetGattDescriptors.
btmuStopBleScanForPaired
Result btmuStopBleScanForPaired(void)
StopBleScanForPaired.
btmuAcquireBlePairingEvent
Result btmuAcquireBlePairingEvent(Event *out_event)
AcquireBlePairingEvent.
btmuAcquireBleConnectionEvent
Result btmuAcquireBleConnectionEvent(Event *out_event)
AcquireBleConnectionEvent.
btmuBleUnPairDevice2
Result btmuBleUnPairDevice2(BtdrvAddress addr, BtdrvBleAdvertisePacketParameter param)
BleUnPairDevice2.
btmuBleUnPairDevice
Result btmuBleUnPairDevice(u32 connection_handle, BtdrvBleAdvertisePacketParameter param)
BleUnPairDevice.
BtmGattDescriptor
GattDescriptor.
Definition: btm_types.h:286
u8
uint8_t u8
8-bit unsigned integer.
Definition: types.h:19
BtmBleDataPath
BleDataPath.
Definition: btm_types.h:294
Event
Kernel-mode event structure.
Definition: event.h:13
btmuGetGattCharacteristics
Result btmuGetGattCharacteristics(u32 connection_handle, u16 service_handle, BtmGattCharacteristic *characteristics, u8 count, u8 *total_out)
GetGattCharacteristics.
btmuGetBleMtu
Result btmuGetBleMtu(u32 connection_handle, u16 *out)
GetBleMtu.
btmuGetGattServices
Result btmuGetGattServices(u32 connection_handle, BtmGattService *services, u8 count, u8 *total_out)
GetGattServices.
btmuStartBleScanForGeneral
Result btmuStartBleScanForGeneral(BtdrvBleAdvertisePacketParameter param)
StartBleScanForGeneral.
btmuGetBleScanFilterParameter
Result btmuGetBleScanFilterParameter(u16 parameter_id, BtdrvBleAdvertisePacketParameter *out)
GetBleScanFilterParameter.
btmuInitialize
Result btmuInitialize(void)
Initialize btm:u.
btmuGetBelongingGattService
Result btmuGetBelongingGattService(u32 connection_handle, u16 attribute_handle, BtmGattService *service, bool *flag)
This is similar to btmuGetGattIncludedServices except this only returns 1 BtmGattService.
btmuBleGetPairedDevices
Result btmuBleGetPairedDevices(BtdrvBleAdvertisePacketParameter param, BtdrvAddress *addrs, u8 count, u8 *total_out)
BleGetPairedDevices.
btmuGetBleScanResultsForGeneral
Result btmuGetBleScanResultsForGeneral(BtdrvBleScanResult *results, u8 count, u8 *total_out)
GetBleScanResultsForGeneral.
u32
uint32_t u32
32-bit unsigned integer.
Definition: types.h:21
btmuGetGattIncludedServices
Result btmuGetGattIncludedServices(u32 connection_handle, u16 service_handle, BtmGattService *services, u8 count, u8 *out)
Same as btmuGetGattServices except this only returns BtmGattService entries where various checks pass...
btmuBlePairDevice
Result btmuBlePairDevice(u32 connection_handle, BtdrvBleAdvertisePacketParameter param)
BlePairDevice.
Result
u32 Result
Function error code result type.
Definition: types.h:44
btmuGetServiceSession_IBtmUserCore
Service * btmuGetServiceSession_IBtmUserCore(void)
Gets the Service object for IBtmUserCore.
btmuGetGattService
Result btmuGetGattService(u32 connection_handle, const BtdrvGattAttributeUuid *uuid, BtmGattService *service, bool *flag)
Same as btmuGetGattServices except this only returns the BtmGattService which matches the input Btdrv...
btmuStopBleScanForSmartDevice
Result btmuStopBleScanForSmartDevice(void)
StopBleScanForSmartDevice.
BtdrvGattAttributeUuid
GattAttributeUuid.
Definition: btdrv_types.h:299
btmuBleGetConnectionState
Result btmuBleGetConnectionState(BtdrvBleConnectionInfo *info, u8 count, u8 *total_out)
BleGetConnectionState.
BtdrvBleConnectionInfo
BleConnectionInfo.
Definition: btdrv_types.h:292
BtmGattCharacteristic
GattCharacteristic.
Definition: btm_types.h:275
btmuAcquireBleMtuConfigEvent
Result btmuAcquireBleMtuConfigEvent(Event *out_event)
AcquireBleMtuConfigEvent.
btmuUnregisterBleGattDataPath
Result btmuUnregisterBleGattDataPath(const BtmBleDataPath *path)
UnregisterBleGattDataPath.
BtdrvAddress
Address.
Definition: btdrv_types.h:161
Service
Service object structure.
Definition: service.h:13
BtmGattService
GattService.
Definition: btm_types.h:263
btmuAcquireBleScanEvent
Result btmuAcquireBleScanEvent(Event *out_event)
AcquireBleScanEvent.
BtdrvBleScanResult
BleScanResult.
Definition: btdrv_types.h:283
btmuExit
void btmuExit(void)
Exit btm:u.
btmuStartBleScanForPaired
Result btmuStartBleScanForPaired(BtdrvBleAdvertisePacketParameter param)
StartBleScanForPaired.
BtdrvBleAdvertisePacketParameter
BleAdvertisePacketParameter.
Definition: btdrv_types.h:278
btmuGetServiceSession
Result btmuGetServiceSession(Service *srv_out)
Gets the Service object for the actual btm:u service session. This object must be closed by the user ...
btmuStartBleScanForSmartDevice
Result btmuStartBleScanForSmartDevice(const BtdrvGattAttributeUuid *uuid)
StartBleScanForSmartDevice.
u16
uint16_t u16
16-bit unsigned integer.
Definition: types.h:20
btmuBleDisconnect
Result btmuBleDisconnect(u32 connection_handle)
BleDisconnect.
btmuStopBleScanForGeneral
Result btmuStopBleScanForGeneral(void)
StopBleScanForGeneral.
btmuConfigureBleMtu
Result btmuConfigureBleMtu(u32 connection_handle, u16 mtu)
ConfigureBleMtu.
btmuBleConnect
Result btmuBleConnect(BtdrvAddress addr)
BleConnect.
btmuGetBleScanResultsForSmartDevice
Result btmuGetBleScanResultsForSmartDevice(BtdrvBleScanResult *results, u8 count, u8 *total_out)
GetBleScanResultsForSmartDevice.
btmuGetBleScanFilterParameter2
Result btmuGetBleScanFilterParameter2(u16 parameter_id, BtdrvGattAttributeUuid *out)
GetBleScanFilterParameter2.