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/BLETypes.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 ?
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         address_t address;
00310         Span<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_ */