Received-SPF: pass (google.com: domain of linux-bluetooth-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Content-Type: text/plain;
        charset=us-ascii
Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.100.0.2.22\))
Subject: Re: [PATCH BlueZ] doc/agent-api: Add AuthenticationFailed method
From:   Marcel Holtmann <marcel@holtmann.org>
In-Reply-To: <20210623184355.3685859-1-luiz.dentz@gmail.com>
Date:   Sat, 26 Jun 2021 07:44:52 +0200
Cc:     linux-bluetooth@vger.kernel.org
Content-Transfer-Encoding: 8BIT
Message-Id: <0571E549-AFD1-4EB4-90E9-F2825F1CAA86@holtmann.org>
References: <20210623184355.3685859-1-luiz.dentz@gmail.com>
To:     Luiz Augusto von Dentz <luiz.dentz@gmail.com>
Precedence: bulk

Hi Luiz,

> This introduces AuthenticationFailed method which is used to indicate
> when there was an authentication failure with a remote device which is
> recommended by the core spec:
> 
> BLUETOOTH CORE SPECIFICATION Version 5.2 | Vol 3, Part C page 1314:
> '5.2.2.3 Simple Pairing after authentication failure
> When the link key is stored, subsequent connections to the same device
> will use authentication but this may fail if the remote device has
> deleted the link key. Table 5.2 defines what shall be done depending
> on the type of the link key and whether bonding was performed or not.'
> 
> So following Table 5.2 recommendation the AuthenticationFailed method
> would be called when authentication fails with a bonded device.
> ---
> doc/agent-api.txt | 5 +++++
> 1 file changed, 5 insertions(+)
> 
> diff --git a/doc/agent-api.txt b/doc/agent-api.txt
> index 0d9347cab..91d752b0a 100644
> --- a/doc/agent-api.txt
> +++ b/doc/agent-api.txt
> @@ -183,3 +183,8 @@ Methods		void Release()
> 
> 			This method gets called to indicate that the agent
> 			request failed before a reply was returned.
> +
> +		void AuthenticationFailed(object device, byte status)
> +
> +			This method indicates that there was an authentication
> +			failure with a remote device.

you are forgetting to describe what status is for.

Also if we follow the language from the previous agent method, then this should be IndicateAuthenticationFailure. I know it is a mouthful, but we always phrased the method names as action or information targeting a user or UI to do something.

Regards

Marcel