RE: DAP-ISSUE-129: Simplify Network Service Discovery API [Network Service Discovery]

> -----Original Message-----
> From: ext Device APIs Working Group Issue Tracker
> [mailto:sysbot+tracker@w3.org]
> Sent: Tuesday, July 09, 2013 1:17 PM
> To: public-device-apis@w3.org
> Subject: DAP-ISSUE-129: Simplify Network Service Discovery API [Network
> Service Discovery]
>
> DAP-ISSUE-129: Simplify Network Service Discovery API [Network Service
> Discovery]
>
> http://www.w3.org/2009/dap/track/issues/129
>
> Raised by: Jean-Claude Dufourd
> On product: Network Service Discovery
>
> from email: http://lists.w3.org/Archives/Public/public-device-
> apis/2013Jun/0015.html
>
>
> The current NSD API is used in this sequence:
> - NSD.getNetworkServices( "type", callback, errorcb)
> - then in callback, you immediately set the onserviceavailable callback and
> you return, because usually, the first NetworkServices object you get is
> empty

Re "usually, the first NetworkServices object you get is empty": This depends 
on the UA implementation. If the UA continuously monitors network traffic for 
device announcement messages, it would always have a list of currently 
available devices on hand, and the NetworkServices object returned in the 
success callback would contain the matching devices for which the user grants 
permission. In this case, an empty NetworkServices object in the success 
callback would indicate that there are no matching devices available to the 
web app (either no matching devices are available on the network at all, or 
the user did not grant permission to any available ones). On the other hand, 
if a UA does not continuously monitor network traffic for device announcement 
messages, and only issues a search when the getNetworkServices method is 
called, then the NetworkServices object returned in the success callback would 
most likely be empty, regardless of what devices are available on the network.

I think this discrepancy in the meaning of an empty NetworkServices object 
might affect interoperability and is worth taking a closer look at.

> - then onserviceavailable is called, and in there you call
> NSD.getNetworkServices( "type", callback, errorcb) again
> - then in callback, you immediately set the onserviceavailable callback and
> you do the actual work.
>
> You need to define:
> - a function calling NSD.getNetworkServices( "type", successcallback,
> errorcb)
> - a onserviceavailable callback that calls NSD.getNetworkServices( "type",
> successcallback, errorcb)
> - the successcallback.
>
> It is possible to define a wrapper around this to deal with the
> onserviceavailable process transparently for the author, on top of the
> existing API.
> Thus, I avoid the need for the definition of onserviceavailable.
>
> The actual code does the same as above, but the process that the webapp
> author sees is:
> - discover( "type", callback, errorcb)
> - then in callback, you immediately do the actual work.
>

Is "callback" meant to be a one-time callback or to be called many times 
potentially?

> Why not simplify the API and get rid of the need for onserviceavaible ?
> Why make the API more complex than it needs to be ?
> Why expose a more intricate process that brings no advantage ?
>

I think the two-step process has its value. After supplying the initial batch 
of devices to the web app, onserviceavailable continues to notify the web app 
if and when new devices become available on the network [if the UA continues 
to monitor network traffic for device announcements]. The callback allows the 
web app to take control of when to re-invoke getNetworkServices, which would 
likely result in user permission prompts. In the model that you're suggesting, 
[again, if the UA continues to monitor network traffic for device 
announcements,] whenever a matching device shows up in the network, the user 
would be prompted if he wants to grant permission to the web app to access the 
matching devices. Imagine that your web app is streaming media from a media 
server. If the user gets a prompt every time a media server pops up in the 
network (which can be more frequent than you think if you consider media 
servers running on mobile phones that go online and offline all the time to 
preserve power) while watching a movie, that can be very frustrating. On the 
other hand, with the model in the current spec, the web app can choose to 
defer the call to getNetworkServices (and hence the user permission prompt) to 
a more convenient time.

Regards, Cathy.

> Best regards
> JC
>
> Note: here is a possible implementation of the wrapper avoiding the need
> for onserviceavailable:
>
> function discover(serviceType, callBack, errcb) {
>
>      var thisFunction = function (services) {
>
>          services.onserviceavailable = function () {
>
>              NSD.getNetworkServices(serviceType, thisFunction, errcb);
>
>          };
>
>          if (services.length > 0) {
>
>              callBack.call(this, services);
>
>          }
>
>      };
>
>      NSD.getNetworkServices(serviceType, thisFunction, errcb);
>
> }
>
>
>