Hello all, *** Background
When the application initiates a BLE connection, it specifies a callback to associate with the connection attempt. The host reports the result of the connect attempt to the application via a call to this callback. After a connection is successfully established, the host retains the callback and further uses it to communicate subsequent events related to the connection (e.g., connection dropped, mtu changed, etc.). The callback accepts a `struct ble_gap_event` parameter, which communicates the specifics of the event being reported. One field in this struct, `type`, indicates the event type. This email concerns one event type in particular: `BLE_GAP_EVENT_CONN_CANCEL`. The host generates an event of this type when the application cancels a connect attempt before it completes. That is, the following sequence yields this event: 1. Application initiates a connection (`ble_gap_connect()`). 2. BLE stack begins the connect procedure. 3. Application cancels the connect attempt (`ble_gap_conn_cancel()`). 4. BLE stack stops attempting to connect. At the end of this sequence, the BLE host reports the successful cancellation with a `BLE_GAP_EVENT_CONN_CANCEL` event. *** Proposal I propose that we remove the `BLE_GAP_EVENT_CONN_CANCEL` event. Instead of using this event type, the host would report a successful cancellation via a `BLE_GAP_EVENT_CONNECT` event with an appropriate status code. My rationale for this proposal is as follows. If you think of the BLE stack as a state machine, a successful cancellation involves the same state transition as a failed connect attempt. In both cases, the stack transitions from "connecting" to "idle". For this reason, I think it is easier for the application to handle both cases with the same code. I imagine the application doesn't care whether a connect attempt failed due to timeout or because it was cancelled. In both cases, the upshot is that the connection wasn't established, and the application is now free to initiate another connection. I believe the cause of failure is mainly used in reporting the event, and the status code should give all the necessary information for this. *** Details * For cancelled connection attempts, I suggest the `BLE_GAP_EVENT_CONNECT` event specify a status code of `BLE_HS_EAPP` (application error). This is not a perfect fit, but I am leery of adding more error codes, as that imposes a burden on unrelated application code. * Because this is an API change, it would be best to introduce it slowly. The `BLE_GAP_CONN_CANCEL` event would be marked deprecated in the next release, and then removed entirely in the one after that. * The numeric identifiers associated with the event types would not change. Instead, 2 (`BLE_GAP_CONN_CANCEL`) would be labelled "reserved". All comments welcome. Thanks, Chris
