[BlueZ,2/3] doc/device: Add Disconnected signal

---
 doc/org.bluez.Device.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

Hi Luiz,

On 19/05/2025 18:44, Luiz Augusto von Dentz wrote:
> Hi Frédéric,
>
> On Mon, May 19, 2025 at 12:18 PM Frédéric Danis
> <frederic.danis@collabora.com> wrote:
>> ---
>>   doc/org.bluez.Device.rst | 17 +++++++++++++++++
>>   1 file changed, 17 insertions(+)
>>
>> diff --git a/doc/org.bluez.Device.rst b/doc/org.bluez.Device.rst
>> index 80501eddd..6229f95ad 100644
>> --- a/doc/org.bluez.Device.rst
>> +++ b/doc/org.bluez.Device.rst
>> @@ -155,6 +155,23 @@ array{array{byte}} GetServiceRecords() [experimental]
>>          :org.bluez.Error.NotConnected:
>>          :org.bluez.Error.DoesNotExist:
>>
>> +Signals
>> +-------
>> +
>> +void Disconnected(string reason)
>> +````````````````````````````````
>> +
>> +       This signal is launched when a device is disconnected with the reason of
>> +       the disconnection.
>> +
>> +       Possible reasons:
>> +
>> +       :disconnection-unknown:
>> +       :disconnection-timeout:
>> +       :disconnection-local-host:
>> +       :disconnection-remote:
>> +       :disconnection-local-suspend:
> Perhaps it would be better to use to the actual HCI code instead of
> converting it to string, since I suspect application using this signal
> may want to recover the actual error to do some sort of reconnecting
> policy, etc, or having them both in case the client just wants to
> print it.

I will update the patch to use the numerical value.

But, the reason provided by MGMT_EV_DEVICE_DISCONNECTED is not the
HCI code but a mgmt value translated in net/bluetooth/hci_event.c
(https://github.com/bluez/bluetooth-next/blob/master/net/bluetooth/hci_event.c#L3366)

On Tue, 2025-05-20 at 11:32 +0200, Frédéric Danis wrote:
> Hi Bastien,
> 
> On 19/05/2025 21:22, Bastien Nocera wrote:
> > On Mon, 2025-05-19 at 12:44 -0400, Luiz Augusto von Dentz wrote:
> > > Hi Frédéric,
> > > 
> > > On Mon, May 19, 2025 at 12:18 PM Frédéric Danis
> > > <frederic.danis@collabora.com> wrote:
> > > > ---
> > > >   doc/org.bluez.Device.rst | 17 +++++++++++++++++
> > > >   1 file changed, 17 insertions(+)
> > > > 
> > > > diff --git a/doc/org.bluez.Device.rst
> > > > b/doc/org.bluez.Device.rst
> > > > index 80501eddd..6229f95ad 100644
> > > > --- a/doc/org.bluez.Device.rst
> > > > +++ b/doc/org.bluez.Device.rst
> > > > @@ -155,6 +155,23 @@ array{array{byte}} GetServiceRecords()
> > > > [experimental]
> > > >          :org.bluez.Error.NotConnected:
> > > >          :org.bluez.Error.DoesNotExist:
> > > > 
> > > > +Signals
> > > > +-------
> > > > +
> > > > +void Disconnected(string reason)
> > > > +````````````````````````````````
> > > > +
> > > > +       This signal is launched when a device is disconnected
> > > > with
> > > > the reason of
> > > > +       the disconnection.
> > > > +
> > > > +       Possible reasons:
> > > > +
> > > > +       :disconnection-unknown:
> > > > +       :disconnection-timeout:
> > > > +       :disconnection-local-host:
> > > > +       :disconnection-remote:
> > > > +       :disconnection-local-suspend:
> > > Perhaps it would be better to use to the actual HCI code instead
> > > of
> > > converting it to string, since I suspect application using this
> > > signal
> > > may want to recover the actual error to do some sort of
> > > reconnecting
> > > policy, etc, or having them both in case the client just wants to
> > > print it.
> > If there are applications using those signals (I'm guessing,
> > Bluetooth
> > settings apps), whatever the format of the error, could we have an
> > expected behaviour associated with individual error types?
> 
> This could be used by client apps like Bluetooth setting to try to
> reconnect to the device in case of timeout or unknown disconnection,
> or to try to connect to another device depending on internal policy.

I meant having that information in the docs :)

Cheers