michaelh/zephyr
1
0
Fork 0
Code Releases Activity

Bluetooth: Fix documentation and other issues with auth callbacks

Browse source 
Provide proper documentation for all of the authentication callbacks,
and clarify the usage of the cancel callback. Previously the cancel
callback was always required, even though that doesn't necessarily
make sense now that the pairing_complete/failed callbacks exist.

Fixes #8385

Signed-off-by: Johan Hedberg <johan.hedberg@intel.com>
This commit is contained in:
Johan Hedberg 2018-07-30 20:26:48 +03:00 • committed by Johan Hedberg
commit 4752788c81
3 changed files with 134 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

114
include/bluetooth/conn.h
View file

@ -384,12 +384,122 @@ void bt_conn_cb_register(struct bt_conn_cb *cb);
/** Authenticated pairing callback structure */
struct bt_conn_auth_cb {
/** @brief Display a passkey to the user.
*
* When called the application is expected to display the given
* passkey to the user, with the expectation that the passkey will
* then be entered on the peer device. The passkey will be in the
* range of 0 - 999999, and is expected to be padded with zeroes so
* that six digits are always shown. E.g. the value 37 should be
* shown as 000037.
*
* This callback may be set to NULL, which means that the local
* device lacks the ability do display a passkey. If set
* to non-NULL the cancel callback must also be provided, since
* this is the only way the application can find out that it should
* stop displaying the passkey.
*
* @param conn Connection where pairing is currently active.
* @param passkey Passkey to show to the user.
*/
void (*passkey_display)(struct bt_conn *conn, unsigned int passkey);
/** @brief Request the user to enter a passkey.
*
* When called the user is expected to enter a passkey. The passkey
* must be in the range of 0 - 999999, and should be expected to
* be zero-padded, as that's how the peer device will typically be
* showing it (e.g. 37 would be shown as 000037).
*
* Once the user has entered the passkey its value should be given
* to the stack using the bt_conn_auth_passkey_entry() API.
*
* This callback may be set to NULL, which means that the local
* device lacks the ability to enter a passkey. If set to non-NULL
* the cancel callback must also be provided, since this is the
* only way the application can find out that it should stop
* requesting the user to enter a passkey.
*
* @param conn Connection where pairing is currently active.
*/
void (*passkey_entry)(struct bt_conn *conn);
/** @brief Request the user to confirm a passkey.
*
* When called the user is expected to confirm that the given
* passkey is also shown on the peer device.. The passkey will
* be in the range of 0 - 999999, and should be zero-padded to
* always be six digits (e.g. 37 would be shown as 000037).
*
* Once the user has confirmed the passkey to match, the
* bt_conn_auth_passkey_confirm() API should be called. If the
* user concluded that the passkey doesn't match the
* bt_conn_auth_cancel() API should be called.
*
* This callback may be set to NULL, which means that the local
* device lacks the ability to confirm a passkey. If set to non-NULL
* the cancel callback must also be provided, since this is the
* only way the application can find out that it should stop
* requesting the user to confirm a passkey.
*
* @param conn Connection where pairing is currently active.
* @param passkey Passkey to be confirmed.
*/
void (*passkey_confirm)(struct bt_conn *conn, unsigned int passkey);
/** @brief Cancel the ongoing user request.
*
* This callback will be called to notify the application that it
* should cancel any previous user request (passkey display, entry
* or confirmation).
*
* This may be set to NULL, but must always be provided whenever the
* passkey_display, passkey_entry passkey_confirm or pairing_confirm
* callback has been provided.
*
* @param conn Connection where pairing is currently active.
*/
void (*cancel)(struct bt_conn *conn);
/** @brief Request confirmation for an incoming pairing.
*
* This callback will be called to confirm an incoming pairing
* request where none of the other user callbacks is applicable.
*
* If the user decides to accept the pairing the
* bt_conn_auth_pairing_confirm() API should be called. If the
* user decides to reject the pairing the bt_conn_auth_cancel() API
* should be called.
*
* This callback may be set to NULL, which means that the local
* device lacks the ability to confirm a pairing request. If set
* to non-NULL the cancel callback must also be provided, since
* this is the only way the application can find out that it should
* stop requesting the user to confirm a pairing request.
*
* @param conn Connection where pairing is currently active.
*/
void (*pairing_confirm)(struct bt_conn *conn);
#if defined(CONFIG_BT_BREDR)
/** @brief Request the user to enter a passkey.
*
* This callback will be called for a BR/EDR (Bluetooth Classic)
* connection where pairing is being performed. Once called the
* user is expected to enter a PIN code with a length between
* 1 and 16 digits. If the @a highsec parameter is set to true
* the PIN code must be 16 digits long.
*
* Once entered, the PIN code should be given to the stack using
* the bt_conn_auth_pincode_entry() API.
*
* This callback may be set to NULL, however in that case pairing
* over BR/EDR will not be possible. If provided, the cancel
* callback must be provided as well.
*
* @param conn Connection where pairing is currently active.
* @param highsec true if 16 digit PIN is required.
*/
void (*pincode_entry)(struct bt_conn *conn, bool highsec);
#endif
@ -412,8 +522,8 @@ struct bt_conn_auth_cb {
/** @brief Register authentication callbacks.
*
* Register callbacks to handle authenticated pairing. Passing NULL unregisters
* previous callbacks structure.
* Register callbacks to handle authenticated pairing. Passing NULL
* unregisters a previous callbacks structure.
*
* @param cb Callback struct.
*