Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
GapEvents.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2017-2017 ARM Limited 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef BLE_PAL_GAP_MESSAGE_H_ 00018 #define BLE_PAL_GAP_MESSAGE_H_ 00019 00020 #include "GapTypes.h" 00021 #include "ble/ArrayView.h " 00022 00023 namespace ble { 00024 namespace pal { 00025 00026 /** 00027 * Enumeration of GAP event types 00028 */ 00029 struct GapEventType : SafeEnum<GapEventType, uint8_t> { 00030 enum type { 00031 /** 00032 * Event type used by GapUnexpectedErrorEvent 00033 */ 00034 UNEXPECTED_ERROR, 00035 00036 /** 00037 * Event type used by GapConnectionCompleteEvent 00038 */ 00039 CONNECTION_COMPLETE, 00040 00041 /** 00042 * Event type used by GapAdvertisingReportEvent 00043 */ 00044 ADVERTISING_REPORT, 00045 00046 /** 00047 * Event type used by GapConnectionUpdateEvent 00048 * */ 00049 CONNECTION_UPDATE, 00050 00051 /** 00052 * Event type used by GapRemoteConnectionParameterRequestEvent 00053 */ 00054 REMOTE_CONNECTION_PARAMETER_REQUEST, 00055 00056 /** 00057 * Event type used by GapDisconnectionCompleteEvent 00058 */ 00059 DISCONNECTION_COMPLETE 00060 }; 00061 00062 GapEventType(type event_type) : SafeEnum<GapEventType, uint8_t>(event_type) { } 00063 }; 00064 00065 00066 /** 00067 * Base class of a Gap Event. 00068 * 00069 * Client should use the field type to deduce the actual type of the event. 00070 */ 00071 struct GapEvent { 00072 00073 const GapEventType type; 00074 00075 protected: 00076 GapEvent(GapEventType type) : type(type) { } 00077 00078 // Disable copy construction and copy assignement operations. 00079 GapEvent(const GapEvent&); 00080 GapEvent& operator=(const GapEvent&); 00081 }; 00082 00083 00084 /** 00085 * Model an unexpected error that happen during a gap procedure. 00086 * 00087 * This class is mainly used to notify user code of an unexpected error returned 00088 * in an HCI command complete event. 00089 */ 00090 struct GapUnexpectedErrorEvent : public GapEvent { 00091 GapUnexpectedErrorEvent(uint16_t opcode, uint8_t error_code) : 00092 GapEvent(GapEventType::UNEXPECTED_ERROR), 00093 opcode(opcode), error_code(error_code) { } 00094 00095 /** 00096 * Opcode composed of the OCF and OGF of the command which has returned an 00097 * error. 00098 */ 00099 const uint16_t opcode; 00100 00101 /** 00102 * Error code 00103 */ 00104 const uint8_t error_code; 00105 }; 00106 00107 00108 /** 00109 * Indicate to both ends (slave or master) the end of the connection process. 00110 * 00111 * This structure should be used for Connection Complete Events and Enhanced 00112 * Connection Complete Event. 00113 * 00114 * @note: See Bluetooth 5 Vol 2 PartE: 7.7.65.1 LE Connection Complete Event 00115 * @note: See Bluetooth 5 Vol 2 PartE: 7.7.65.10 LE Enhanced Connection 00116 */ 00117 struct GapConnectionCompleteEvent : public GapEvent { 00118 /** 00119 * Construct a new GapConnectionCompleteEvent. 00120 * 00121 * @param status Status of the operation: 0x00 in case of success otherwise 00122 * the error code associated with the failure. 00123 * 00124 * @param connection_handle handle of the connection created. This handle 00125 * will be used to address the connection in any connection oriented 00126 * operation. 00127 * 00128 * @param role Role of the LE subsystem in the connection. 00129 * 00130 * @param address_type Type of address used by the peer for this connection. 00131 * 00132 * @param address Address of the peer used to establish the connection. 00133 * 00134 * @param connection_interval Connection interval used on this connection. 00135 * It shall be in a range [0x0006 : 0x0C80]. A unit is equal to 1.25ms. 00136 * 00137 * @param connection_latency Number of connection events the slave can 00138 * drop. 00139 * 00140 * @param supervision_timeout Supervision timeout of the connection. It 00141 * shall be in the range [0x000A : 0x0C80] where a unit represent 10ms. 00142 * 00143 * @note: See Bluetooth 5 Vol 2 PartE: 7.7.65.10 LE Enhanced Connection 00144 * Complete Event 00145 */ 00146 GapConnectionCompleteEvent( 00147 uint8_t status, 00148 connection_handle_t connection_handle, 00149 connection_role_t role, 00150 advertising_peer_address_type_t peer_address_type, 00151 const address_t& peer_address, 00152 uint16_t connection_interval, 00153 uint16_t connection_latency, 00154 uint16_t supervision_timeout 00155 ) : 00156 GapEvent(GapEventType::CONNECTION_COMPLETE), 00157 status(status), 00158 connection_handle(connection_handle), 00159 role(role), 00160 peer_address_type( 00161 peer_address_type == advertising_peer_address_type_t::PUBLIC_ADDRESS ? 00162 peer_address_type_t::PUBLIC : 00163 peer_address_type_t::RANDOM 00164 ), 00165 peer_address(peer_address), 00166 connection_interval(connection_interval), 00167 connection_latency(connection_latency), 00168 supervision_timeout(supervision_timeout), 00169 local_resolvable_private_address(), 00170 peer_resolvable_private_address() { 00171 } 00172 00173 /** 00174 * Construct a new GapConnectionCompleteEvent. 00175 * 00176 * @param status Status of the operation: 0x00 in case of success otherwise 00177 * the error code associated with the failure. 00178 * 00179 * @param connection_handle handle of the connection created. This handle 00180 * will be used to address the connection in any connection oriented 00181 * operation. 00182 * 00183 * @param role Role of the LE subsystem in the connection. 00184 * 00185 * @param address_type Type of address used by the peer for this connection. 00186 * 00187 * @param address Address of the peer used to establish the connection. 00188 * 00189 * @param connection_interval Connection interval used on this connection. 00190 * It shall be in a range [0x0006 : 0x0C80]. A unit is equal to 1.25ms. 00191 * 00192 * @param connection_latency Number of connection events the slave can 00193 * drop. 00194 * 00195 * @param supervision_timeout Supervision timeout of the connection. It 00196 * shall be in the range [0x000A : 0x0C80] where a unit represent 10ms. 00197 * 00198 * @param local_resolvable_private_address Resolvable private address used 00199 * by the local device to establish the connection. 00200 * 00201 * @param peer_resolvable_private_address Resolvable private address used 00202 * by the peer to establish the connection. 00203 * 00204 * @note: See Bluetooth 5 Vol 2 PartE: 7.7.65.10 LE Enhanced Connection 00205 * Complete Event 00206 */ 00207 GapConnectionCompleteEvent( 00208 uint8_t status, 00209 connection_handle_t connection_handle, 00210 connection_role_t role, 00211 peer_address_type_t peer_address_type, 00212 const address_t& peer_address, 00213 uint16_t connection_interval, 00214 uint16_t connection_latency, 00215 uint16_t supervision_timeout, 00216 const address_t& local_resolvable_private_address, 00217 const address_t& peer_resolvable_private_address 00218 ) : 00219 GapEvent(GapEventType::CONNECTION_COMPLETE), 00220 status(status), 00221 connection_handle(connection_handle), 00222 role(role), 00223 peer_address_type(peer_address_type), 00224 peer_address(peer_address), 00225 connection_interval(connection_interval), 00226 connection_latency(connection_latency), 00227 supervision_timeout(supervision_timeout), 00228 local_resolvable_private_address(local_resolvable_private_address), 00229 peer_resolvable_private_address(peer_resolvable_private_address) { 00230 } 00231 00232 00233 /* 00234 * @param status Indicate if the connection succesfully completed or not: 00235 * - 0: Connection successfuly completed 00236 * - [0x01 : 0xFF] Connection failed to complete, the value represent 00237 * the code for the error. 00238 */ 00239 const uint8_t status; 00240 00241 /** 00242 * Handle of the connection created, valid if status is equal to 0. 00243 * @attention Valid if status is equal to 0. 00244 */ 00245 const connection_handle_t connection_handle; 00246 00247 /** 00248 * Role of the device in the connection 00249 * @attention Valid if status is equal to 0. 00250 */ 00251 const connection_role_t role; 00252 00253 /** 00254 * Peer address type. 00255 */ 00256 const peer_address_type_t peer_address_type; 00257 00258 /** 00259 * Peer address. 00260 */ 00261 const address_t peer_address; 00262 00263 /** 00264 * Connection interval used in this connection. 00265 * It shall be in a range [0x0006 : 0x0C80]. A unit is equal to 1.25ms. 00266 */ 00267 const uint16_t connection_interval; 00268 00269 /** 00270 * Number of connection events the slave can drop. 00271 */ 00272 const uint16_t connection_latency; 00273 00274 /** 00275 * Supervision timeout of the connection 00276 * It shall be in the range [0x000A : 0x0C80] where a unit represent 10ms. 00277 */ 00278 const uint16_t supervision_timeout; 00279 00280 /** 00281 * Resolvable private address of the local device. 00282 * Set to all 0 if not available. 00283 */ 00284 const address_t local_resolvable_private_address; 00285 00286 /** 00287 * Resolvable private address of the peer. 00288 * Set to all 0 if not available. * 00289 */ 00290 const address_t peer_resolvable_private_address; 00291 }; 00292 00293 00294 /** 00295 * Report advertising from one or more LE device. 00296 * 00297 * @attention This class has to be implemented by the BLE port. 00298 * 00299 * @note: See Bluetooth 5 Vol 2 PartE: 7.7.65.2 LE Advertising Report Event 00300 */ 00301 struct GapAdvertisingReportEvent : public GapEvent { 00302 00303 /** 00304 * POD representing an advertising captured by the LE subsystem. 00305 */ 00306 struct advertising_t { 00307 received_advertising_type_t type; 00308 connection_peer_address_type_t address_type; 00309 const address_t& address; 00310 ArrayView<const uint8_t> data; 00311 int8_t rssi; 00312 }; 00313 00314 GapAdvertisingReportEvent() : GapEvent(GapEventType::ADVERTISING_REPORT) { } 00315 00316 virtual ~GapAdvertisingReportEvent() { } 00317 00318 /** 00319 * Count of advertising in this event. 00320 */ 00321 virtual uint8_t size() const = 0; 00322 00323 /** 00324 * Access the advertising at index i. 00325 */ 00326 virtual advertising_t operator[](uint8_t i) const = 0; 00327 }; 00328 00329 00330 /** 00331 * Indicates the connection update process completion. 00332 * 00333 * If no parameters are updated after a connection update request from the peer 00334 * then this event shall not be emmited. 00335 * 00336 * @note: See Bluetooth 5 Vol 2 PartE: 7.7.65.3 LE Connection Update Complete 00337 * Event. 00338 */ 00339 struct GapConnectionUpdateEvent : public GapEvent { 00340 00341 /** 00342 * Construct a connection update event for a successful process. 00343 * 00344 * @param status Status of the connection update event operation. If equal 00345 * to 0x00 then the process was successful, otherwise the status indicates 00346 * the reason of the faillure. 00347 * 00348 * @param connection_handle Handle of the connection updated. 00349 * 00350 * @param connection_interval New connection interval used by the connection. 00351 * 00352 * @param Connection_latency New connection latency used by the connection. 00353 * 00354 * @param supervision_timeout New connection supervision timeout. 00355 */ 00356 GapConnectionUpdateEvent( 00357 uint8_t status, 00358 connection_handle_t connection_handle, 00359 uint16_t connection_interval, 00360 uint16_t connection_latency, 00361 uint16_t supervision_timeout 00362 ) : 00363 GapEvent(GapEventType::CONNECTION_UPDATE), 00364 status(status), 00365 connection_handle(connection_handle), 00366 connection_interval(connection_interval), 00367 connection_latency(connection_latency), 00368 supervision_timeout(supervision_timeout) { 00369 } 00370 00371 /** 00372 * If equal to 0, the connection update has succesfully completed otherwise 00373 * the process has failled and this field represent the error associated to 00374 * the faillure. 00375 */ 00376 const uint8_t status; 00377 00378 /** 00379 * Handle of the connection which has completed the connection update 00380 * process. 00381 */ 00382 const connection_handle_t connection_handle; 00383 00384 /** 00385 * New connection interval used by the connection. 00386 * It shall be in a range [0x0006 : 0x0C80]. A unit is equal to 1.25ms. 00387 */ 00388 const uint16_t connection_interval; 00389 00390 /* 00391 * New number of connection events the slave can drop. 00392 */ 00393 const uint16_t connection_latency; 00394 00395 /* 00396 * New supervision timeout of the connection. 00397 * It shall be in the range [0x000A : 0x0C80] where a unit represent 10ms. 00398 */ 00399 const uint16_t supervision_timeout; 00400 }; 00401 00402 00403 /** 00404 * indicate a request from the peer to change the connection parameters. 00405 * 00406 * @note: See Bluetooth 5 Vol 2 PartE: 7.7.65.6 LE Remote Connection Parameter 00407 * Request Event. 00408 */ 00409 struct GapRemoteConnectionParameterRequestEvent : public GapEvent { 00410 /** 00411 * Construct a new remote connection parameter request event. 00412 * 00413 * @param connection_handle Handle of the connection with the peer 00414 * requesting the parameter update 00415 * 00416 * @param min_connection_interval Minimum value of the connection interval 00417 * requested by the peer. 00418 * 00419 * @param max_connection_interval Maximum value of the connection interval 00420 * requested by the peer. 00421 * 00422 * @param connection_latency Slave latency requested by the peer. 00423 * 00424 * @param supervision_timeout Supervision timeout requested by the peer. 00425 */ 00426 GapRemoteConnectionParameterRequestEvent( 00427 connection_handle_t connection_handle, 00428 uint16_t min_connection_interval, 00429 uint16_t max_connection_interval, 00430 uint16_t connection_latency, 00431 uint16_t supervision_timeout 00432 ) : GapEvent(GapEventType::REMOTE_CONNECTION_PARAMETER_REQUEST), 00433 connection_handle(connection_handle), 00434 min_connection_interval(min_connection_interval), 00435 max_connection_interval(max_connection_interval), 00436 connection_latency(connection_latency), 00437 supervision_timeout(supervision_timeout) { 00438 } 00439 00440 /** 00441 * Handle of the connection with the peer requesting the parameter update. 00442 */ 00443 const connection_handle_t connection_handle; 00444 00445 /** 00446 * Minimum value of the connection interval requested by the peer. 00447 * It shall be in a range [0x0006 : 0x0C80]. A unit is equal to 1.25ms. 00448 */ 00449 const uint16_t min_connection_interval; 00450 00451 /** 00452 * Maximum value of the connection interval requested by the peer. 00453 * It shall be in a range [0x0006 : 0x0C80]. A unit is equal to 1.25ms. 00454 */ 00455 const uint16_t max_connection_interval; 00456 00457 /* 00458 * Slave latency requested by the peer. 00459 */ 00460 const uint16_t connection_latency; 00461 00462 /* 00463 * Supervision timeout requested by the peer. 00464 * It shall be in the range [0x000A : 0x0C80] where a unit represent 10ms. 00465 */ 00466 const uint16_t supervision_timeout; 00467 }; 00468 00469 00470 /** 00471 * Indicate the end of a disconnection process. 00472 * 00473 * @note: See Bluetooth 5 Vol 2 PartE: 7.7.5 Disconnection Complete Event. 00474 */ 00475 struct GapDisconnectionCompleteEvent : public GapEvent { 00476 /** 00477 * Construct a disconnection complete event. 00478 * 00479 * @param status Status of the procedure. If equal to 0 then the 00480 * disconnection process complete successfully. Otherwise it represents the 00481 * error code associated with the faillure. 00482 * 00483 * @param connection_handle Handle of the connection disconnected. 00484 * 00485 * @param reason Reason of the disconnection 00486 */ 00487 GapDisconnectionCompleteEvent( 00488 uint8_t status, 00489 connection_handle_t connection_handle, 00490 uint8_t reason 00491 ) : GapEvent(GapEventType::DISCONNECTION_COMPLETE), 00492 status(status), 00493 connection_handle(connection_handle), 00494 reason(reason) { 00495 } 00496 00497 /** 00498 * Status of the procedure. If equal to 0 then the procedure was a success 00499 * otherwise this variable contains the error code associated with the 00500 * faillure. 00501 */ 00502 const uint8_t status; 00503 00504 /** 00505 * Handle of the connection used for the procedure. 00506 */ 00507 const connection_handle_t connection_handle; 00508 00509 /** 00510 * Reason for disconnection. 00511 * 00512 * @attention ignored in case of faillure. 00513 */ 00514 const uint8_t reason; 00515 }; 00516 00517 } // namespace pal 00518 } // namespace ble 00519 00520 #endif /* BLE_PAL_GAP_MESSAGE_H_ */
Generated on Tue Jul 12 2022 12:44:15 by
