From:  Valentin Gosu <valentin.gosu@gmail.com>
Date:  10 Sep 2014 07:27:16 Hong Kong Time
Newsgroup:  news.mozilla.org/mozilla.dev.tech.network
Subject:  

API for nsICaptivePortalService

NNTP-Posting-Host:  63.245.216.66

Hi,

I'm currently working on a service in Necko to detect whenever the browser
is on a network with a captive portal.
I've gathered some info at [1] and I'm going to use
nsICaptivePortalDetector (which is currently used in FirefoxOS, and managed
by gonk/NetworkManager [2]) to implement the service in Bug 1048131.

I'm trying to figure out the API that Gecko consumers would need to query
and/or be notified of changes to the state of captive-portal.

I have identified 4 ways to get the captive portal status:
1. sync - just check the isCaptive attribute - may return a stale result
2. async - the service calls a callback ASAP with the captive-portal state
3. captive notification - register a callback, which the service calls once
it detects a captive portal
4. not-captive notification  - register a callback, which gets called once
the captive portal goes away ( assumes we are currently in a captive portal
)

How it would work:
The polling mode of the servicce makes a request every _interval_ seconds
to a predefined URL, and checks against the expected result. This updates
the isCaptive attribute that can be checked.
The async way would make the same request, and return the status.

I expect registering a callback to be called whenever we encounter a
captive portal( or exit one), would be especially useful, but I'm not sure
if that's always safe - We would be holding a reference to the object
implementing the callback for a long time possibly.

Another feature would be the recheckCaptivePortal method, which is called
from different components in Gecko, when an event occurs that might signify
we are in a captive portal (511 redirect, or redirect to local address),
and would trigger a recheck of the captive-portal status.

My WIP patch provides the following interface.
Let me know if there are important features missing, or if some of them are
not needed.

[scriptable, uuid(b5fd5629-d04c-4138-9529-9311f291ecd4)]
interface nsICaptivePortalServiceCallback : nsISupports
{
  /**
   * Invoke callbacks after captive portal detection finished.
   */
  void complete(in long status, in nsresult error);
};

/**
 * Service used for captive portal detection.
 */
[scriptable, uuid(bdbe0555-fc3d-4f7b-9205-c309ceb2d641)]
interface nsICaptivePortalService : nsISupports
{
   void initialize();
   void start(); // starts polling
   void stop(); // stops polling

   void checkCaptive(in nsICaptivePortalServiceCallback callback);
   void registerCaptiveCallback(in nsICaptivePortalServiceCallback
callback);
   void registerNotCaptiveCallback(in nsICaptivePortalServiceCallback
callback);
   // an event has occured that might suggest a captive portal is active
   void recheckCaptivePortal(in long reason);

   readonly attribute boolean isCaptive;
   attribute uint32_t interval;
};

[1] https://wiki.mozilla.org/Necko/CaptivePortal
[2]
http://dxr.mozilla.org/mozilla-central/source/dom/system/gonk/NetworkManager.js