Comments on the ConnectDevice API function

Comments on the ConnectDevice API function

[Martin Woolley]

Hello

I've recently been working with BlueZ via D-Bus and have a situation which requires me to be able to connect to a device whose Bluetooth device address is known, but without first scanning. This is a link layer state transition with the specification allows.

BlueZ currently supports this via an API adapter function called ConnectDevice, whose status is currently "experimental". From my experience of using this function, it seems to behave like this:

If the BlueZ instance has not scanned yet, so that the target device is not known to it, the ConnectDevice call results in scanning taking place and then if the target device is found, it is connected to. Success!

But if scanning has previously been performed, regardless of the state of the actual device (e.g. advertising and ready to accept connections), an exception is thrown with a message whose text value is "Already Exists".

I was wondering if I could influence the design of the API before the ConnectDevice experimental status is removed? 

I would like to suggest that there should be no need for a special API to connect directly to a device without first scanning. Why burden the application developer needing to call it just in case this condition applies, catching the BlueZ exception ("Already Exists") and responding by then calling the normal Connect API? 

An alternative would be to accommodate this special case (not scanned before) in the implementation of the standard device Connect(bdaddr) function or if that makes no sense because Device objects must correspond to previously discovered, physical devices, then at least the adapter ConnectDevice function could take care of the two possible paths and simplify matters for the application developer. 

Thanks in anticipation.

Martin Woolley 
Senior Developer Relations Manager, EMEA  |  Bluetooth Special Interest Group, Inc.

Re: Comments on the ConnectDevice API function

[Luiz Augusto von Dentz]

Hi Martin,

On Fri, May 22, 2020 at 1:25 AM Martin Woolley <mwoolley@bluetooth.com> wrote:
>
> Hello
>
> I've recently been working with BlueZ via D-Bus and have a situation which requires me to be able to connect to a device whose Bluetooth device address is known, but without first scanning. This is a link layer state transition with the specification allows.
>
> BlueZ currently supports this via an API adapter function called ConnectDevice, whose status is currently "experimental". From my experience of using this function, it seems to behave like this:
>
> If the BlueZ instance has not scanned yet, so that the target device is not known to it, the ConnectDevice call results in scanning taking place and then if the target device is found, it is connected to. Success!
>
> But if scanning has previously been performed, regardless of the state of the actual device (e.g. advertising and ready to accept connections), an exception is thrown with a message whose text value is "Already Exists".
>
> I was wondering if I could influence the design of the API before the ConnectDevice experimental status is removed?
>
> I would like to suggest that there should be no need for a special API to connect directly to a device without first scanning. Why burden the application developer needing to call it just in case this condition applies, catching the BlueZ exception ("Already Exists") and responding by then calling the normal Connect API?

I guess the intention was to have the application use the intended API
for devices already present _before_ calling ConnectDevice, so before
entering the address manually the application would enumerate the
existing devices and figure out if that was already present.

> An alternative would be to accommodate this special case (not scanned before) in the implementation of the standard device Connect(bdaddr) function or if that makes no sense because Device objects must correspond to previously discovered, physical devices, then at least the adapter ConnectDevice function could take care of the two possible paths and simplify matters for the application developer.

I guess you probably know this but just in case someone look at the
archives it is better that we make some things clearer, while the core
spec allows connecting without scanning D-Bus are intend to be a
higher level API thus why ConnectDevice was not really necessary for a
long time and we just introduced it for qualification purpose or when
there are multiple adapter where one acts as scanner. Also ever since
the introduction of privacy (random addresses) APIs that takes
addresses becomes rather complicated to be used directly, and there
exists ways to scan for a specific address with pattern filtering:
https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/adapter-api.txt#n122

That said I don't oppose to remove Already Exists error, but we should
be very clear that the use of such API should only be recommended with
users input and does not substitute the likes of Device.Connect.

-- 
Luiz Augusto von Dentz

RE: Comments on the ConnectDevice API function

[Martin Woolley]

Hi Luiz

thanks for your response. Much appreciated. I must confess this is the first time I've used the BlueZ APIs directly (via D-Bus). 

I'm all for hiding implementation details where possible in APIs and making the API itself take care of conditional aspects if possible, but these were just my $0.02, no more than that. I wasn't aware of the background or the philosophy, so thanks for that insight as well.

Having the API take care of the AlreadyExists error by providing a connection to the already discovered device, transparently does seem a nice touch for the application developer but certainly not essential.

All the best

Martin

-----Original Message-----
From: Luiz Augusto von Dentz <luiz.dentz@gmail.com> 
Sent: 22 May 2020 18:49
To: Martin Woolley <mwoolley@bluetooth.com>
Cc: Linux-bluetooth@vger.kernel.org
Subject: Re: Comments on the ConnectDevice API function

Hi Martin,

On Fri, May 22, 2020 at 1:25 AM Martin Woolley <mwoolley@bluetooth.com> wrote:
>
> Hello
>
> I've recently been working with BlueZ via D-Bus and have a situation which requires me to be able to connect to a device whose Bluetooth device address is known, but without first scanning. This is a link layer state transition with the specification allows.
>
> BlueZ currently supports this via an API adapter function called ConnectDevice, whose status is currently "experimental". From my experience of using this function, it seems to behave like this:
>
> If the BlueZ instance has not scanned yet, so that the target device is not known to it, the ConnectDevice call results in scanning taking place and then if the target device is found, it is connected to. Success!
>
> But if scanning has previously been performed, regardless of the state of the actual device (e.g. advertising and ready to accept connections), an exception is thrown with a message whose text value is "Already Exists".
>
> I was wondering if I could influence the design of the API before the ConnectDevice experimental status is removed?
>
> I would like to suggest that there should be no need for a special API to connect directly to a device without first scanning. Why burden the application developer needing to call it just in case this condition applies, catching the BlueZ exception ("Already Exists") and responding by then calling the normal Connect API?

I guess the intention was to have the application use the intended API for devices already present _before_ calling ConnectDevice, so before entering the address manually the application would enumerate the existing devices and figure out if that was already present.

> An alternative would be to accommodate this special case (not scanned before) in the implementation of the standard device Connect(bdaddr) function or if that makes no sense because Device objects must correspond to previously discovered, physical devices, then at least the adapter ConnectDevice function could take care of the two possible paths and simplify matters for the application developer.

I guess you probably know this but just in case someone look at the archives it is better that we make some things clearer, while the core spec allows connecting without scanning D-Bus are intend to be a higher level API thus why ConnectDevice was not really necessary for a long time and we just introduced it for qualification purpose or when there are multiple adapter where one acts as scanner. Also ever since the introduction of privacy (random addresses) APIs that takes addresses becomes rather complicated to be used directly, and there exists ways to scan for a specific address with pattern filtering:
https://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgit.kernel.org%2Fpub%2Fscm%2Fbluetooth%2Fbluez.git%2Ftree%2Fdoc%2Fadapter-api.txt%23n122&amp;data=02%7C01%7C%7Cfafcb0f940054867612508d7fe7866fb%7Ce4e0fec5fc6c4dd6ae374bdb30e156b9%7C0%7C0%7C637257665400787125&amp;sdata=Iy%2FwWkxs%2FyW3gL239FLWdoDRGa0apb63WxMhYwRoneM%3D&amp;reserved=0

That said I don't oppose to remove Already Exists error, but we should be very clear that the use of such API should only be recommended with users input and does not substitute the likes of Device.Connect.

--
Luiz Augusto von Dentz

Re: Comments on the ConnectDevice API function

[Szymon Janc]

Hi Martin,

On Wednesday, 27 May 2020 15:41:12 CEST Martin Woolley wrote:
> Hi Luiz
> 
> thanks for your response. Much appreciated. I must confess this is the first
> time I've used the BlueZ APIs directly (via D-Bus). 
 
> I'm all for hiding implementation details where possible in APIs and making
> the API itself take care of conditional aspects if possible, but these were
> just my $0.02, no more than that. I wasn't aware of the background or the
> philosophy, so thanks for that insight as well.
 
> Having the API take care of the AlreadyExists error by providing a
> connection to the already discovered device, transparently does seem a nice
> touch for the application developer but certainly not essential.

This API was added only for qualification purposes (there are some GAP tests 
specified in a way that upper tester is not doing discovery) and it shouldn't 
be used for 'normal' usage.


 
> All the best
> 
> Martin
> 
> -----Original Message-----
> From: Luiz Augusto von Dentz <luiz.dentz@gmail.com> 
> Sent: 22 May 2020 18:49
> To: Martin Woolley <mwoolley@bluetooth.com>
> Cc: Linux-bluetooth@vger.kernel.org
> Subject: Re: Comments on the ConnectDevice API function
> 
> Hi Martin,
> 
> On Fri, May 22, 2020 at 1:25 AM Martin Woolley <mwoolley@bluetooth.com>
> wrote:
> >
> >
> > Hello
> >
> >
> >
> > I've recently been working with BlueZ via D-Bus and have a situation which
> > requires me to be able to connect to a device whose Bluetooth device
> > address is known, but without first scanning. This is a link layer state
> > transition with the specification allows.
>
> >
> >
> > BlueZ currently supports this via an API adapter function called
> > ConnectDevice, whose status is currently "experimental". From my
> > experience of using this function, it seems to behave like this:
>
> >
> >
> > If the BlueZ instance has not scanned yet, so that the target device is
> > not known to it, the ConnectDevice call results in scanning taking place
> > and then if the target device is found, it is connected to. Success!
>
> >
> >
> > But if scanning has previously been performed, regardless of the state of
> > the actual device (e.g. advertising and ready to accept connections), an
> > exception is thrown with a message whose text value is "Already Exists".
>
> >
> >
> > I was wondering if I could influence the design of the API before the
> > ConnectDevice experimental status is removed?
>
> >
> >
> > I would like to suggest that there should be no need for a special API to
> > connect directly to a device without first scanning. Why burden the
> > application developer needing to call it just in case this condition
> > applies, catching the BlueZ exception ("Already Exists") and responding
> > by then calling the normal Connect API?
> 
> I guess the intention was to have the application use the intended API for
> devices already present _before_ calling ConnectDevice, so before entering
> the address manually the application would enumerate the existing devices
> and figure out if that was already present.
 
> 
> > An alternative would be to accommodate this special case (not scanned
> > before) in the implementation of the standard device Connect(bdaddr)
> > function or if that makes no sense because Device objects must correspond
> > to previously discovered, physical devices, then at least the adapter
> > ConnectDevice function could take care of the two possible paths and
> > simplify matters for the application developer.
> 
> I guess you probably know this but just in case someone look at the archives
> it is better that we make some things clearer, while the core spec allows
> connecting without scanning D-Bus are intend to be a higher level API thus
> why ConnectDevice was not really necessary for a long time and we just
> introduced it for qualification purpose or when there are multiple adapter
> where one acts as scanner. Also ever since the introduction of privacy
> (random addresses) APIs that takes addresses becomes rather complicated to
> be used directly, and there exists ways to scan for a specific address with
> pattern filtering:
> https://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgit.kerne
> l.org%2Fpub%2Fscm%2Fbluetooth%2Fbluez.git%2Ftree%2Fdoc%2Fadapter-api.txt%23n
> 122&amp;data=02%7C01%7C%7Cfafcb0f940054867612508d7fe7866fb%7Ce4e0fec5fc6c4dd
> 6ae374bdb30e156b9%7C0%7C0%7C637257665400787125&amp;sdata=Iy%2FwWkxs%2FyW3gL2
> 39FLWdoDRGa0apb63WxMhYwRoneM%3D&amp;reserved=0 
> That said I don't oppose to remove Already Exists error, but we should be
> very clear that the use of such API should only be recommended with users
> input and does not substitute the likes of Device.Connect.
 
> --
> Luiz Augusto von Dentz


-- 
pozdrawiam
Szymon Janc

Re: Comments on the ConnectDevice API function

[Luiz Augusto von Dentz]

Hi Szymon,

On Wed, May 27, 2020 at 7:10 AM Szymon Janc <szymon.janc@codecoup.pl> wrote:
>
> Hi Martin,
>
> On Wednesday, 27 May 2020 15:41:12 CEST Martin Woolley wrote:
> > Hi Luiz
> >
> > thanks for your response. Much appreciated. I must confess this is the first
> > time I've used the BlueZ APIs directly (via D-Bus).
>
> > I'm all for hiding implementation details where possible in APIs and making
> > the API itself take care of conditional aspects if possible, but these were
> > just my $0.02, no more than that. I wasn't aware of the background or the
> > philosophy, so thanks for that insight as well.
>
> > Having the API take care of the AlreadyExists error by providing a
> > connection to the already discovered device, transparently does seem a nice
> > touch for the application developer but certainly not essential.
>
> This API was added only for qualification purposes (there are some GAP tests
> specified in a way that upper tester is not doing discovery) and it shouldn't
> be used for 'normal' usage.

Btw, we could perhaps have a different flag from such API e.g.
qualification-only or perhaps add an entry on main.conf would be
better in this regard since it may mean that we never really adopt
them as stable APIs.

>
>
> > All the best
> >
> > Martin
> >
> > -----Original Message-----
> > From: Luiz Augusto von Dentz <luiz.dentz@gmail.com>
> > Sent: 22 May 2020 18:49
> > To: Martin Woolley <mwoolley@bluetooth.com>
> > Cc: Linux-bluetooth@vger.kernel.org
> > Subject: Re: Comments on the ConnectDevice API function
> >
> > Hi Martin,
> >
> > On Fri, May 22, 2020 at 1:25 AM Martin Woolley <mwoolley@bluetooth.com>
> > wrote:
> > >
> > >
> > > Hello
> > >
> > >
> > >
> > > I've recently been working with BlueZ via D-Bus and have a situation which
> > > requires me to be able to connect to a device whose Bluetooth device
> > > address is known, but without first scanning. This is a link layer state
> > > transition with the specification allows.
> >
> > >
> > >
> > > BlueZ currently supports this via an API adapter function called
> > > ConnectDevice, whose status is currently "experimental". From my
> > > experience of using this function, it seems to behave like this:
> >
> > >
> > >
> > > If the BlueZ instance has not scanned yet, so that the target device is
> > > not known to it, the ConnectDevice call results in scanning taking place
> > > and then if the target device is found, it is connected to. Success!
> >
> > >
> > >
> > > But if scanning has previously been performed, regardless of the state of
> > > the actual device (e.g. advertising and ready to accept connections), an
> > > exception is thrown with a message whose text value is "Already Exists".
> >
> > >
> > >
> > > I was wondering if I could influence the design of the API before the
> > > ConnectDevice experimental status is removed?
> >
> > >
> > >
> > > I would like to suggest that there should be no need for a special API to
> > > connect directly to a device without first scanning. Why burden the
> > > application developer needing to call it just in case this condition
> > > applies, catching the BlueZ exception ("Already Exists") and responding
> > > by then calling the normal Connect API?
> >
> > I guess the intention was to have the application use the intended API for
> > devices already present _before_ calling ConnectDevice, so before entering
> > the address manually the application would enumerate the existing devices
> > and figure out if that was already present.
>
> >
> > > An alternative would be to accommodate this special case (not scanned
> > > before) in the implementation of the standard device Connect(bdaddr)
> > > function or if that makes no sense because Device objects must correspond
> > > to previously discovered, physical devices, then at least the adapter
> > > ConnectDevice function could take care of the two possible paths and
> > > simplify matters for the application developer.
> >
> > I guess you probably know this but just in case someone look at the archives
> > it is better that we make some things clearer, while the core spec allows
> > connecting without scanning D-Bus are intend to be a higher level API thus
> > why ConnectDevice was not really necessary for a long time and we just
> > introduced it for qualification purpose or when there are multiple adapter
> > where one acts as scanner. Also ever since the introduction of privacy
> > (random addresses) APIs that takes addresses becomes rather complicated to
> > be used directly, and there exists ways to scan for a specific address with
> > pattern filtering:
> > https://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgit.kerne
> > l.org%2Fpub%2Fscm%2Fbluetooth%2Fbluez.git%2Ftree%2Fdoc%2Fadapter-api.txt%23n
> > 122&amp;data=02%7C01%7C%7Cfafcb0f940054867612508d7fe7866fb%7Ce4e0fec5fc6c4dd
> > 6ae374bdb30e156b9%7C0%7C0%7C637257665400787125&amp;sdata=Iy%2FwWkxs%2FyW3gL2
> > 39FLWdoDRGa0apb63WxMhYwRoneM%3D&amp;reserved=0
> > That said I don't oppose to remove Already Exists error, but we should be
> > very clear that the use of such API should only be recommended with users
> > input and does not substitute the likes of Device.Connect.
>
> > --
> > Luiz Augusto von Dentz
>
>
> --
> pozdrawiam
> Szymon Janc
>
>


-- 
Luiz Augusto von Dentz

RE: Comments on the ConnectDevice API function

[Martin Woolley]

Regarding an alternative to the "experimental" flag, that would make sense, as would some words in the adapter.txt API documentation which explain why the method exists and the constraints regarding its use.

I have to say, I'm a little troubled by the very idea of a function/method which was only "added for qualification" by which I assume it is meant that the method was added solely to allow the qualification tests to be passed, but which the intention is that it must never be used in a real product or solution. That doesn't sound in line with the intentions of Bluetooth qualification. Or did I misunderstand?

-----Original Message-----
From: Luiz Augusto von Dentz <luiz.dentz@gmail.com> 
Sent: 27 May 2020 16:39
To: Szymon Janc <szymon.janc@codecoup.pl>
Cc: Martin Woolley <mwoolley@bluetooth.com>; Linux-bluetooth@vger.kernel.org
Subject: Re: Comments on the ConnectDevice API function

Hi Szymon,

On Wed, May 27, 2020 at 7:10 AM Szymon Janc <szymon.janc@codecoup.pl> wrote:
>
> Hi Martin,
>
> On Wednesday, 27 May 2020 15:41:12 CEST Martin Woolley wrote:
> > Hi Luiz
> >
> > thanks for your response. Much appreciated. I must confess this is 
> > the first time I've used the BlueZ APIs directly (via D-Bus).
>
> > I'm all for hiding implementation details where possible in APIs and 
> > making the API itself take care of conditional aspects if possible, 
> > but these were just my $0.02, no more than that. I wasn't aware of 
> > the background or the philosophy, so thanks for that insight as well.
>
> > Having the API take care of the AlreadyExists error by providing a 
> > connection to the already discovered device, transparently does seem 
> > a nice touch for the application developer but certainly not essential.
>
> This API was added only for qualification purposes (there are some GAP 
> tests specified in a way that upper tester is not doing discovery) and 
> it shouldn't be used for 'normal' usage.

Btw, we could perhaps have a different flag from such API e.g.
qualification-only or perhaps add an entry on main.conf would be better in this regard since it may mean that we never really adopt them as stable APIs.

>
>
> > All the best
> >
> > Martin
> >
> > -----Original Message-----
> > From: Luiz Augusto von Dentz <luiz.dentz@gmail.com>
> > Sent: 22 May 2020 18:49
> > To: Martin Woolley <mwoolley@bluetooth.com>
> > Cc: Linux-bluetooth@vger.kernel.org
> > Subject: Re: Comments on the ConnectDevice API function
> >
> > Hi Martin,
> >
> > On Fri, May 22, 2020 at 1:25 AM Martin Woolley 
> > <mwoolley@bluetooth.com>
> > wrote:
> > >
> > >
> > > Hello
> > >
> > >
> > >
> > > I've recently been working with BlueZ via D-Bus and have a 
> > > situation which requires me to be able to connect to a device 
> > > whose Bluetooth device address is known, but without first 
> > > scanning. This is a link layer state transition with the specification allows.
> >
> > >
> > >
> > > BlueZ currently supports this via an API adapter function called 
> > > ConnectDevice, whose status is currently "experimental". From my 
> > > experience of using this function, it seems to behave like this:
> >
> > >
> > >
> > > If the BlueZ instance has not scanned yet, so that the target 
> > > device is not known to it, the ConnectDevice call results in 
> > > scanning taking place and then if the target device is found, it is connected to. Success!
> >
> > >
> > >
> > > But if scanning has previously been performed, regardless of the 
> > > state of the actual device (e.g. advertising and ready to accept 
> > > connections), an exception is thrown with a message whose text value is "Already Exists".
> >
> > >
> > >
> > > I was wondering if I could influence the design of the API before 
> > > the ConnectDevice experimental status is removed?
> >
> > >
> > >
> > > I would like to suggest that there should be no need for a special 
> > > API to connect directly to a device without first scanning. Why 
> > > burden the application developer needing to call it just in case 
> > > this condition applies, catching the BlueZ exception ("Already 
> > > Exists") and responding by then calling the normal Connect API?
> >
> > I guess the intention was to have the application use the intended 
> > API for devices already present _before_ calling ConnectDevice, so 
> > before entering the address manually the application would enumerate 
> > the existing devices and figure out if that was already present.
>
> >
> > > An alternative would be to accommodate this special case (not 
> > > scanned
> > > before) in the implementation of the standard device 
> > > Connect(bdaddr) function or if that makes no sense because Device 
> > > objects must correspond to previously discovered, physical 
> > > devices, then at least the adapter ConnectDevice function could 
> > > take care of the two possible paths and simplify matters for the application developer.
> >
> > I guess you probably know this but just in case someone look at the 
> > archives it is better that we make some things clearer, while the 
> > core spec allows connecting without scanning D-Bus are intend to be 
> > a higher level API thus why ConnectDevice was not really necessary 
> > for a long time and we just introduced it for qualification purpose 
> > or when there are multiple adapter where one acts as scanner. Also 
> > ever since the introduction of privacy (random addresses) APIs that 
> > takes addresses becomes rather complicated to be used directly, and 
> > there exists ways to scan for a specific address with pattern filtering:
> > https://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgi
> > t.kerne 
> > l.org%2Fpub%2Fscm%2Fbluetooth%2Fbluez.git%2Ftree%2Fdoc%2Fadapter-api
> > .txt%23n 
> > 122&amp;data=02%7C01%7C%7Cfafcb0f940054867612508d7fe7866fb%7Ce4e0fec
> > 5fc6c4dd
> > 6ae374bdb30e156b9%7C0%7C0%7C637257665400787125&amp;sdata=Iy%2FwWkxs%
> > 2FyW3gL2
> > 39FLWdoDRGa0apb63WxMhYwRoneM%3D&amp;reserved=0
> > That said I don't oppose to remove Already Exists error, but we 
> > should be very clear that the use of such API should only be 
> > recommended with users input and does not substitute the likes of Device.Connect.
>
> > --
> > Luiz Augusto von Dentz
>
>
> --
> pozdrawiam
> Szymon Janc
>
>


--
Luiz Augusto von Dentz

RE: Comments on the ConnectDevice API function

[Martin Woolley]

Ignore my comment about being "troubled"! You probably did anyway. I think I understand what is meant now..... that API allows some part of the stack to be exercised for the purposes of qualification testing. That doesn't mean the API itself has to be generally available. I got there in the end.

-----Original Message-----
From: linux-bluetooth-owner@vger.kernel.org <linux-bluetooth-owner@vger.kernel.org> On Behalf Of Martin Woolley
Sent: 27 May 2020 17:10
To: Luiz Augusto von Dentz <luiz.dentz@gmail.com>; Szymon Janc <szymon.janc@codecoup.pl>
Cc: Linux-bluetooth@vger.kernel.org
Subject: RE: Comments on the ConnectDevice API function

Regarding an alternative to the "experimental" flag, that would make sense, as would some words in the adapter.txt API documentation which explain why the method exists and the constraints regarding its use.

I have to say, I'm a little troubled by the very idea of a function/method which was only "added for qualification" by which I assume it is meant that the method was added solely to allow the qualification tests to be passed, but which the intention is that it must never be used in a real product or solution. That doesn't sound in line with the intentions of Bluetooth qualification. Or did I misunderstand?

-----Original Message-----
From: Luiz Augusto von Dentz <luiz.dentz@gmail.com>
Sent: 27 May 2020 16:39
To: Szymon Janc <szymon.janc@codecoup.pl>
Cc: Martin Woolley <mwoolley@bluetooth.com>; Linux-bluetooth@vger.kernel.org
Subject: Re: Comments on the ConnectDevice API function

Hi Szymon,

On Wed, May 27, 2020 at 7:10 AM Szymon Janc <szymon.janc@codecoup.pl> wrote:
>
> Hi Martin,
>
> On Wednesday, 27 May 2020 15:41:12 CEST Martin Woolley wrote:
> > Hi Luiz
> >
> > thanks for your response. Much appreciated. I must confess this is 
> > the first time I've used the BlueZ APIs directly (via D-Bus).
>
> > I'm all for hiding implementation details where possible in APIs and 
> > making the API itself take care of conditional aspects if possible, 
> > but these were just my $0.02, no more than that. I wasn't aware of 
> > the background or the philosophy, so thanks for that insight as well.
>
> > Having the API take care of the AlreadyExists error by providing a 
> > connection to the already discovered device, transparently does seem 
> > a nice touch for the application developer but certainly not essential.
>
> This API was added only for qualification purposes (there are some GAP 
> tests specified in a way that upper tester is not doing discovery) and 
> it shouldn't be used for 'normal' usage.

Btw, we could perhaps have a different flag from such API e.g.
qualification-only or perhaps add an entry on main.conf would be better in this regard since it may mean that we never really adopt them as stable APIs.

>
>
> > All the best
> >
> > Martin
> >
> > -----Original Message-----
> > From: Luiz Augusto von Dentz <luiz.dentz@gmail.com>
> > Sent: 22 May 2020 18:49
> > To: Martin Woolley <mwoolley@bluetooth.com>
> > Cc: Linux-bluetooth@vger.kernel.org
> > Subject: Re: Comments on the ConnectDevice API function
> >
> > Hi Martin,
> >
> > On Fri, May 22, 2020 at 1:25 AM Martin Woolley 
> > <mwoolley@bluetooth.com>
> > wrote:
> > >
> > >
> > > Hello
> > >
> > >
> > >
> > > I've recently been working with BlueZ via D-Bus and have a 
> > > situation which requires me to be able to connect to a device 
> > > whose Bluetooth device address is known, but without first 
> > > scanning. This is a link layer state transition with the specification allows.
> >
> > >
> > >
> > > BlueZ currently supports this via an API adapter function called 
> > > ConnectDevice, whose status is currently "experimental". From my 
> > > experience of using this function, it seems to behave like this:
> >
> > >
> > >
> > > If the BlueZ instance has not scanned yet, so that the target 
> > > device is not known to it, the ConnectDevice call results in 
> > > scanning taking place and then if the target device is found, it is connected to. Success!
> >
> > >
> > >
> > > But if scanning has previously been performed, regardless of the 
> > > state of the actual device (e.g. advertising and ready to accept 
> > > connections), an exception is thrown with a message whose text value is "Already Exists".
> >
> > >
> > >
> > > I was wondering if I could influence the design of the API before 
> > > the ConnectDevice experimental status is removed?
> >
> > >
> > >
> > > I would like to suggest that there should be no need for a special 
> > > API to connect directly to a device without first scanning. Why 
> > > burden the application developer needing to call it just in case 
> > > this condition applies, catching the BlueZ exception ("Already
> > > Exists") and responding by then calling the normal Connect API?
> >
> > I guess the intention was to have the application use the intended 
> > API for devices already present _before_ calling ConnectDevice, so 
> > before entering the address manually the application would enumerate 
> > the existing devices and figure out if that was already present.
>
> >
> > > An alternative would be to accommodate this special case (not 
> > > scanned
> > > before) in the implementation of the standard device
> > > Connect(bdaddr) function or if that makes no sense because Device 
> > > objects must correspond to previously discovered, physical 
> > > devices, then at least the adapter ConnectDevice function could 
> > > take care of the two possible paths and simplify matters for the application developer.
> >
> > I guess you probably know this but just in case someone look at the 
> > archives it is better that we make some things clearer, while the 
> > core spec allows connecting without scanning D-Bus are intend to be 
> > a higher level API thus why ConnectDevice was not really necessary 
> > for a long time and we just introduced it for qualification purpose 
> > or when there are multiple adapter where one acts as scanner. Also 
> > ever since the introduction of privacy (random addresses) APIs that 
> > takes addresses becomes rather complicated to be used directly, and 
> > there exists ways to scan for a specific address with pattern filtering:
> > https://nam12.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgi
> > t.kerne
> > l.org%2Fpub%2Fscm%2Fbluetooth%2Fbluez.git%2Ftree%2Fdoc%2Fadapter-api
> > .txt%23n
> > 122&amp;data=02%7C01%7C%7Cfafcb0f940054867612508d7fe7866fb%7Ce4e0fec
> > 5fc6c4dd
> > 6ae374bdb30e156b9%7C0%7C0%7C637257665400787125&amp;sdata=Iy%2FwWkxs%
> > 2FyW3gL2
> > 39FLWdoDRGa0apb63WxMhYwRoneM%3D&amp;reserved=0
> > That said I don't oppose to remove Already Exists error, but we 
> > should be very clear that the use of such API should only be 
> > recommended with users input and does not substitute the likes of Device.Connect.
>
> > --
> > Luiz Augusto von Dentz
>
>
> --
> pozdrawiam
> Szymon Janc
>
>


--
Luiz Augusto von Dentz