[PATCH 7/7] doc: document access point scanning

[PATCH 7/7] doc: document access point scanning

[James Prestwood]

[-- Attachment #1: Type: text/plain, Size: 1440 bytes --]

---
 doc/access-point-api.txt | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/doc/access-point-api.txt b/doc/access-point-api.txt
index 68ba23c5..3f712cee 100644
--- a/doc/access-point-api.txt
+++ b/doc/access-point-api.txt
@@ -37,6 +37,29 @@ Methods		void Start(string ssid, string psk)
 						net.connman.iwd.AlreadyExists
 						net.connman.iwd.NotFound
 
+		void Scan()
+
+			Schedule a network scan.
+
+			Possible errors:	net.connman.iwd.NotAvailable
+						net.connman.iwd.NotSupported
+						net.connman.iwd.Busy
+						net.connman.iwd.Failed
+
+		array(dict) GetOrderedNetworks()
+
+			Gets the list of networks found after scanning sorted
+			based on signal strength. Each item in the array is a
+			dictionary containing the network Name, SignalStrength,
+			and Security.
+
+			This list will expire similarly to station, and since
+			access points do not do periodic scans the list may
+			become empty after some time and requires scanning
+			again.
+
+			Possible errors:	net.connman.iwd.NotAvailable
+
 Properties	boolean Started [readonly]
 
 			Reflects whether an access point has been started.
@@ -45,3 +68,7 @@ Properties	boolean Started [readonly]
 
 			The SSID being broadcast for a started AP (omitted if
 			AP has not been started)
+
+		boolean Scanning [readonly]
+
+			Reflects whether the access point is scanning.
-- 
2.34.1

Re: [PATCH 7/7] doc: document access point scanning

[Denis Kenzior]

[-- Attachment #1: Type: text/plain, Size: 1112 bytes --]

Hi James,

On 2/22/22 16:57, James Prestwood wrote:
> ---
>   doc/access-point-api.txt | 27 +++++++++++++++++++++++++++
>   1 file changed, 27 insertions(+)
> 

<snip>

> +		array(dict) GetOrderedNetworks()
> +
> +			Gets the list of networks found after scanning sorted
> +			based on signal strength. Each item in the array is a
> +			dictionary containing the network Name, SignalStrength,
> +			and Security.

Security -> Type to be consistent with KnownNetwork / Network interface naming 
of the properties.

> +
> +			This list will expire similarly to station, and since
> +			access points do not do periodic scans the list may
> +			become empty after some time and requires scanning
> +			again.

I'm not sure what this is about?  Scan results don't actually expire in Station 
in the sense that you can keep calling GetOrderedNetworks() forever and get the 
same results, as long as scanning hasn't been performed.  Essentially if 
Scanning hasn't changed, GetOrderedNetworks() results shouldn't change either.

I would expect the same behavior here?

Regards,
-Denis

Re: [PATCH 7/7] doc: document access point scanning

[James Prestwood]

[-- Attachment #1: Type: text/plain, Size: 2116 bytes --]

On Wed, 2022-02-23 at 12:43 -0600, Denis Kenzior wrote:
> Hi James,
> 
> On 2/22/22 16:57, James Prestwood wrote:
> > ---
> >   doc/access-point-api.txt | 27 +++++++++++++++++++++++++++
> >   1 file changed, 27 insertions(+)
> > 
> 
> <snip>
> 
> > +               array(dict) GetOrderedNetworks()
> > +
> > +                       Gets the list of networks found after
> > scanning sorted
> > +                       based on signal strength. Each item in the
> > array is a
> > +                       dictionary containing the network Name,
> > SignalStrength,
> > +                       and Security.
> 
> Security -> Type to be consistent with KnownNetwork / Network
> interface naming 
> of the properties.
> 
> > +
> > +                       This list will expire similarly to station,
> > and since
> > +                       access points do not do periodic scans the
> > list may
> > +                       become empty after some time and requires
> > scanning
> > +                       again.
> 
> I'm not sure what this is about?  Scan results don't actually expire
> in Station 
> in the sense that you can keep calling GetOrderedNetworks() forever
> and get the 
> same results, as long as scanning hasn't been performed.  Essentially
> if 
> Scanning hasn't changed, GetOrderedNetworks() results shouldn't
> change either.

You're right, I was mis-remembering how the expiration works. Since
station does periodic scan the BSS's get thrown out for each scan which
is what I was somewhat trying to mirror here. But as far as
GetOrderedNetworks goes it just takes the current list, however old it
is.

> 
> I would expect the same behavior here?

Sure I can remove the expiration stuff from the core patch and leave it
up to the caller to make sure they get the networks promptly after
scanning is finished.

> 
> Regards,
> -Denis