thali
Version:
2,154 lines (727 loc) • 45.4 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Module: thaliMobile</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">Module: thaliMobile</h1>
<section>
<header>
</header>
<article>
<div class="container-overview">
</div>
<h3 class="subsection-title">Members</h3>
<h4 class="name" id=".connectionTypes"><span class="type-signature">(static, readonly) </span>connectionTypes<span class="type-signature"> :string</span></h4>
<div class="description">
<p>Enum to define the types of connections</p>
</div>
<h5>Type:</h5>
<ul>
<li>
<span class="param-type">string</span>
</li>
</ul>
<h5 class="subsection-title">Properties:</h5>
<table class="props">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>MULTI_PEER_CONNECTIVITY_FRAMEWORK</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>BLUE_TOOTH</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>TCP_NATIVE</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliMobile.js.html">NextGeneration/thaliMobile.js</a>, <a href="NextGeneration_thaliMobile.js.html#line183">line 183</a>
</li></ul></dd>
</dl>
<h4 class="name" id=".emitter"><span class="type-signature">(static) </span>emitter<span class="type-signature"></span></h4>
<div class="description">
<p>Use this emitter to subscribe to events</p>
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliMobile.js.html">NextGeneration/thaliMobile.js</a>, <a href="NextGeneration_thaliMobile.js.html#line504">line 504</a>
</li></ul></dd>
</dl>
<h5>Fires:</h5>
<ul>
<li><a href="module-thaliMobile.html#.event:event:peerAvailabilityChanged">module:thaliMobile.event:peerAvailabilityChanged</a></li>
<li><a href="module-thaliMobile.html#.event:event:discoveryAdvertisingStateUpdate">module:thaliMobile.event:discoveryAdvertisingStateUpdate</a></li>
<li><a href="module-thaliMobile.html#.event:event:networkChanged">module:thaliMobile.event:networkChanged</a></li>
</ul>
<h3 class="subsection-title">Methods</h3>
<h4 class="name" id=".start"><span class="type-signature">(static) </span>start<span class="signature">(router)</span><span class="type-signature"> → {Promise.<<a href="module-thaliMobile.html#~combinedResult">module:thaliMobile~combinedResult</a>>}</span></h4>
<div class="description">
<p>This method MUST be called before any other method here other than
registering for events on the emitter. This method will call start on both
the <a href="module-thaliMobileNativeWrapper.html">module:thaliMobileNativeWrapper</a> singleton and on an instance of
<a href="module-ThaliWifiInfrastructure.html">module:ThaliWifiInfrastructure</a> class. Note that in the case of wifi
this call really does nothing but register the router object. In the case of
native however there is some setup work so an error is more meaningful. If an
error is received from start on either wifi or native then any subsequent
method calls below but stop will not attempt to interact with the failed
type. And yes, if both fail then essentially all the methods but stop turn
into NOOPs.</p>
<p>This method also instructs the system to pay attention to network events.
If one or both radio types is not active but a network changed event
indicates that the relevant radio type is now active and if we are still in
the start state then this code MUST try to call start on the newly activated
radio stack. At that point if the object is in the start state for discovery
or advertising then we MUST also try to call the relevant start methods there
as well.</p>
<p>This method is not idempotent. If called two times in a row without an
intervening stop a "Call Stop!" Error MUST be returned.</p>
<p>This method can be called after stop since this is a singleton object.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>router</code></td>
<td class="type">
<span class="param-type">Object</span>
</td>
<td class="description last"><p>This is an Express Router object (for example,
express-pouchdb is a router object) that the caller wants non-TCP and WiFi
connections to be terminated with. This code will put that router at '/' so
make sure your paths are set up appropriately. If stop is called then the
system will take down the server so it is no longer available.</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliMobile.js.html">NextGeneration/thaliMobile.js</a>, <a href="NextGeneration_thaliMobile.js.html#line68">line 68</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise.<<a href="module-thaliMobile.html#~combinedResult">module:thaliMobile~combinedResult</a>></span>
</dd>
</dl>
<h4 class="name" id=".startListeningForAdvertisements"><span class="type-signature">(static) </span>startListeningForAdvertisements<span class="signature">()</span><span class="type-signature"> → {Promise.<<a href="module-thaliMobile.html#~combinedResult">module:thaliMobile~combinedResult</a>>}</span></h4>
<div class="description">
<p>This method calls the underlying startListeningForAdvertisements on
whichever radio stack is currently in start state. Note that once this method
is called it is giving explicit permission to this code to call this method
on a radio stack that is currently disabled when the method is called but is
later re-enabled due to a network changed event. In other words if <a href="module-thaliMobile.html#.start">module:thaliMobile.start</a> is called and say WiFi doesn't work. Then this
method is called and so advertising is only started for the non-TCP
transport. Then a network changed event happens indicating that WiFi is
available. Since we are still in start state this code will automatically
call <a href="module-ThaliWifiInfrastructure-ThaliWifiInfrastructure.html#start">module:ThaliWifiInfrastructure~ThaliWifiInfrastructure#start</a> and
then will call module:ThaliWifiInfrastructure.startListeningForAdvertisements because we
haven't yet called <a href="module-thaliMobile.html#.stopListeningForAdvertisements">module:thaliMobile.stopListeningForAdvertisements</a>.
If any of the calls triggered by the network event fail then the results MUST
be logged.</p>
<p>This method is idempotent so multiple consecutive calls without an
intervening call to stop will not cause a state change.</p>
<p>This method MUST NOT be called if the object is not in start state or a
"Call Start!" error MUST be returned.</p>
<p>The combinedResult MUST return an error of "Not Active" for any radio type
that we did not call startListeningForAdvertisements on.</p>
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliMobile.js.html">NextGeneration/thaliMobile.js</a>, <a href="NextGeneration_thaliMobile.js.html#line116">line 116</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise.<<a href="module-thaliMobile.html#~combinedResult">module:thaliMobile~combinedResult</a>></span>
</dd>
</dl>
<h4 class="name" id=".startUpdateAdvertisingAndListening"><span class="type-signature">(static) </span>startUpdateAdvertisingAndListening<span class="signature">()</span><span class="type-signature"> → {Promise.<<a href="module-thaliMobile.html#~combinedResult">module:thaliMobile~combinedResult</a>>}</span></h4>
<div class="description">
<p>This method calls the underlying
startUpdateAdvertisingAndListening on whichever radio
stack is currently in start state. This method has the same behavior as
<a href="module-thaliMobile.html#.startListeningForAdvertisements">module:thaliMobile.startListeningForAdvertisements</a> in that if a radio
type that was inactive should later become available and we are in start
state then we will try to call start and if that works and
stopAdvertisingAndListening has not been called then
we will try to call startUpdateAdvertisingAndListening on
the newly started stack. This includes the requirement to log any failed
attempts to call the various methods triggered by a network status change.</p>
<p>Every call to this method is meant to change the current advertising flag
to indicate that new data is available.</p>
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliMobile.js.html">NextGeneration/thaliMobile.js</a>, <a href="NextGeneration_thaliMobile.js.html#line152">line 152</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise.<<a href="module-thaliMobile.html#~combinedResult">module:thaliMobile~combinedResult</a>></span>
</dd>
</dl>
<h4 class="name" id=".stop"><span class="type-signature">(static) </span>stop<span class="signature">()</span><span class="type-signature"> → {Promise.<<a href="module-thaliMobile.html#~combinedResult">module:thaliMobile~combinedResult</a>>}</span></h4>
<div class="description">
<p>This calls stop on both stacks even if start failed.</p>
<p>Once called the object is in stop state.</p>
<p>This method is idempotent and so MUST be able to be called multiple times
in a row without changing state.</p>
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliMobile.js.html">NextGeneration/thaliMobile.js</a>, <a href="NextGeneration_thaliMobile.js.html#line83">line 83</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise.<<a href="module-thaliMobile.html#~combinedResult">module:thaliMobile~combinedResult</a>></span>
</dd>
</dl>
<h4 class="name" id=".stopAdvertisingAndListening"><span class="type-signature">(static) </span>stopAdvertisingAndListening<span class="signature">()</span><span class="type-signature"> → {Promise.<<a href="module-thaliMobile.html#~combinedResult">module:thaliMobile~combinedResult</a>>}</span></h4>
<div class="description">
<p>This method calls the underlying
stopAdvertisingAndListening on both types regardless of
which is in start state.</p>
<p>This method is idempotent and MAY be called even if
startUpateAdvertisingAndListenForIncomingConnections has not been called.</p>
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliMobile.js.html">NextGeneration/thaliMobile.js</a>, <a href="NextGeneration_thaliMobile.js.html#line168">line 168</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise.<<a href="module-thaliMobile.html#~combinedResult">module:thaliMobile~combinedResult</a>></span>
</dd>
</dl>
<h4 class="name" id=".stopListeningForAdvertisements"><span class="type-signature">(static) </span>stopListeningForAdvertisements<span class="signature">()</span><span class="type-signature"> → {Promise.<<a href="module-thaliMobile.html#~combinedResult">module:thaliMobile~combinedResult</a>>}</span></h4>
<div class="description">
<p>This method calls the underlying stopListeningForAdvertisements on both
types regardless of which is in start state.</p>
<p>This method is idempotent and MAY be called even if
startListeningForAdvertisements has not been called.</p>
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliMobile.js.html">NextGeneration/thaliMobile.js</a>, <a href="NextGeneration_thaliMobile.js.html#line130">line 130</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise.<<a href="module-thaliMobile.html#~combinedResult">module:thaliMobile~combinedResult</a>></span>
</dd>
</dl>
<h3 class="subsection-title">Type Definitions</h3>
<h4 class="name" id="~combinedResult">combinedResult</h4>
<div class="description">
<p>This object is our generic status wrapper that lets us return information
about both WiFi and Native.</p>
</div>
<h5>Type:</h5>
<ul>
<li>
<span class="param-type">Object</span>
</li>
</ul>
<h5 class="subsection-title">Properties:</h5>
<table class="props">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>wifiResult</code></td>
<td class="type">
<span class="param-type">Error</span>
</td>
<td class="attributes">
<nullable><br>
</td>
<td class="description last"></td>
</tr>
<tr>
<td class="name"><code>nativeResult</code></td>
<td class="type">
<span class="param-type">Error</span>
</td>
<td class="attributes">
<nullable><br>
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliMobile.js.html">NextGeneration/thaliMobile.js</a>, <a href="NextGeneration_thaliMobile.js.html#line25">line 25</a>
</li></ul></dd>
</dl>
<h4 class="name" id="~discoveryAdvertisingStatus">discoveryAdvertisingStatus</h4>
<div class="description">
<p>Fired whenever our state changes.</p>
</div>
<h5>Type:</h5>
<ul>
<li>
<span class="param-type">Object</span>
</li>
</ul>
<h5 class="subsection-title">Properties:</h5>
<table class="props">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>discoveryActive</code></td>
<td class="type">
<span class="param-type">boolean</span>
</td>
<td class="description last"><p>If true indicates that our goal is to
have discovery active on all available radios.</p></td>
</tr>
<tr>
<td class="name"><code>advertisingActive</code></td>
<td class="type">
<span class="param-type">boolean</span>
</td>
<td class="description last"><p>If true indicates that our goal is to
have advertising active on all available radios.</p></td>
</tr>
<tr>
<td class="name"><code>nonTCPDiscoveryActive</code></td>
<td class="type">
<span class="param-type">boolean</span>
</td>
<td class="description last"><p>Indicates if discovery is active
on the non-TCP transport</p></td>
</tr>
<tr>
<td class="name"><code>nonTCPAdvertisingActive</code></td>
<td class="type">
<span class="param-type">boolean</span>
</td>
<td class="description last"><p>Indicates if advertising is
active on the non-TCP transport</p></td>
</tr>
<tr>
<td class="name"><code>wifiDiscoveryActive</code></td>
<td class="type">
<span class="param-type">boolean</span>
</td>
<td class="description last"><p>Indicates if discovery is active on
WiFi</p></td>
</tr>
<tr>
<td class="name"><code>wifiAdvertisingActive</code></td>
<td class="type">
<span class="param-type">boolean</span>
</td>
<td class="description last"><p>Indicates if advertising is
active on WiFi</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliMobile.js.html">NextGeneration/thaliMobile.js</a>, <a href="NextGeneration_thaliMobile.js.html#line399">line 399</a>
</li></ul></dd>
</dl>
<h3 class="subsection-title">Events</h3>
<h4 class="name" id=".event:event:discoveryAdvertisingStateUpdate">event:discoveryAdvertisingStateUpdate</h4>
<div class="description">
<p>If we receive a module:thaliMobileNativeWrapper~discoveryAdvertisingStateUpdateNonTCPEvent
there are a couple of possibilities:</p>
<ul>
<li>This just confirms whatever command we fired, we started advertising and
it is confirming that. We should only pass on this event the first time it
comes through. If we get multiple events with the same state and they all
match our current state then they should be suppressed.</li>
<li>We thought something was started but now we are getting a notice that it
is stopped. In that case we need to internally record that discovery or
advertising is no longer started and fire this event to update.</li>
<li>We thought something was stopped but now we are getting a notice that
they are started. This can happen because our network change event code
detected that a radio that was off is now on and we are trying to start
things. In that case we should mark the discovery or advertising as started
and fire this event.</li>
</ul>
<p>If we receive a module:ThaliWifiInfrastructure~discoveryAdvertisingStateUpdateWiFiEvent then
the logic is effectively the same as above.</p>
<p>A scary edge case is that we want discovery or advertising off and suddenly
the spontaneously turn on. This shouldn't happen (famous last words) so we'll
ignore it for the moment.</p>
</div>
<h5>Type:</h5>
<ul>
<li>
<span class="param-type">Object</span>
</li>
</ul>
<h5 class="subsection-title">Properties:</h5>
<table class="props">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>discoveryAdvertisingStatus</code></td>
<td class="type">
<span class="param-type"><a href="module-thaliMobile.html#~discoveryAdvertisingStatus">module:thaliMobile~discoveryAdvertisingStatus</a></span>
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliMobile.js.html">NextGeneration/thaliMobile.js</a>, <a href="NextGeneration_thaliMobile.js.html#line418">line 418</a>
</li></ul></dd>
</dl>
<h4 class="name" id=".event:event:networkChanged">event:networkChanged</h4>
<div class="description">
<p>Unless something went horribly wrong only one of thaliMobileNativeWrapper
or ThaliWifiInfrastructure should be enabled for this event at a time. We can
just pass the event value alone.</p>
</div>
<h5>Type:</h5>
<ul>
<li>
<span class="param-type">Object</span>
</li>
</ul>
<h5 class="subsection-title">Properties:</h5>
<table class="props">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>networkChangedValue</code></td>
<td class="type">
<span class="param-type"><a href="module-thaliMobileNative.html#~networkChanged">module:thaliMobileNative~networkChanged</a></span>
</td>
<td class="description last"></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliMobile.js.html">NextGeneration/thaliMobile.js</a>, <a href="NextGeneration_thaliMobile.js.html#line461">line 461</a>
</li></ul></dd>
</dl>
<h4 class="name" id=".event:event:peerAvailabilityChanged">event:peerAvailabilityChanged</h4>
<div class="description">
<p>It is the job of this module to provide the most reliable guesses (and that
is what they are) as to when a peer is and is not available. The module MUST
err on the side of saying that a peer is available over saying they are not
available.</p>
<p>The module MUST guarantee to its listeners (unlike <a href="module-thaliMobileNative.html">module:thaliMobileNative</a>) that once it has fired a peerAvailabilityChanged
event for a specific peerIdentifier + connectionType combination that it will
not fire another peerAvailabilityChanged event for that peerIdentifier +
connectionType combination unless the combination has a new hostAddress or
portNumber.</p>
<p>Note that this code explicitly does not do any kind of duplicate detection
for the same peerIdentifier across different connectionTypes. This is because
we want to surface to the caller all the ways a particular peer is available.</p>
<p>This means that if this code receives multiple redundant notifications from
the various sources it is listening to about the same peerIdentifier and
connectionType combination then it must silently discard the duplicates.</p>
<h2>Android + BLE + Bluetooth</h2><p>When dealing with announcing that a peer has disappeared it is up to this
code to apply relevant heuristics. For example, in the case of Android it is
possible for a Thali app to go into the background. When this happens we
lower the power of the BLE status announcements but we don't change the
Bluetooth power. This means that a peer can seem to disappear when in fact
they are still in range of Bluetooth. This behavior is necessary to preserve
battery. This complicates things because the Android BLE stack never actually
says a peer is gone. Rather it sends a steady stream of announcements that
the peer is available and then stops when it doesn't see the peer anymore. So
this code has to notice those announcements and decide at what point after
they have stopped to declare the peer gone. In general we should experiment
with values like 30 seconds before deciding that a peer is gone. But why not
even longer?</p>
<p><strong>Open Issue:</strong> How long should we wait after we don't hear any updates on
a peer being available over Android before we declare them gone?</p>
<p><strong>Open Issue:</strong> A really obvious optimization would be to hook this code
into the <a href="module-TCPServersManager.html">module:TCPServersManager</a> so it could see if we have a
Bluetooth or MPCF connection running with a particular peer. If we do then
obviously we wouldn't want to declare them gone even if we don't see them on
BLE or if MPCF told us they were gone.</p>
<p>If an attempt to connect to a peer via Bluetooth whose presence we have
previously advertised via peerAvailabilityChanged should fail then we MUST
use our own heuristics to decide if we should mark the peer as no longer
available. Generally speaking if we still see the peer via BLE then we should
continue to mark them as available. Note that available doesn't mean
reachable. It is very easy for a peer to get overwhelmed with Bluetooth
requests and so be near but not able to accept a request.</p>
<p>If we have been notified via a networkChanged event that either BLE or
Bluetooth is no longer available then we MUST mark all peers discovered via
BLE as no longer being present and send peerAvailabilityChanged events
reporting this status change. In theory we could make things more complex by
specifying that if BLE is turned off and Bluetooth isn't then we could
continue to say that the Bluetooth peers are there. But in practical terms it
isn't clear if this situation is possible (e.g. I suspect one can only turn
off Bluetooth, not sub-select between BLE and Bluetooth) and second it's more
complexity than we really need at this point.</p>
<p>If we have been notified via a discoveryAdvertisingStatus event that
discovery is no longer available then we MUST treat existing discovered
Bluetooth peers as no longer being available and send peerAvailabilityChanged
events reporting this fact. Eventually we might get more flexible here and
allow Bluetooth peers to remain "available" and just use the connection
heuristics described previously to mark them as absent when necessary. But
for now let's keep things simple.</p>
<p>If we have been notified via a discoveryAdvertisingStatus event that
advertising is no longer available this should not cause any change in our
information about peers we have discovered or will yet discover.</p>
<h2>iOS + MPCF</h2><p>In the case of the MPCF the native layer has an explicit lostPeer message.
But we aren't completely sure if it's totally reliable. So we either can
immediately declare the peer gone when we get lostPeer or we can take note of
the lostPeer message and then wait a bit before declaring the peer gone. Note
that we would only see this at the Node.js layer via a <a href="module-thaliMobileNativeWrapper.html#~nonTCPPeerAvailabilityChanged">module:thaliMobileNativeWrapper~nonTCPPeerAvailabilityChanged</a> event.</p>
<p><strong>Open Issue:</strong> How does MPCF deal with peers who have gone out of range?
Do they regularly send foundPeer messages or do they send one foundPeer
message and go quiet until they send a lostPeer message after a bit?</p>
<p><strong>Open Issue:</strong> How reliable is the lostPeer message from MPCF? I believe
we have had a suspicion that even if we get a lostPeer we might still be able
to open a connection to that peer successfully (this would make sense if
discovery is over Bluetooth and data transfer over Wifi). But we need to now
make this concrete since we have to decide if we are going to put this
suspicion into our code.</p>
<p>If an attempt to connect to a peer via MPCF whose presence we have previously
advertised via peerAvailabilityChanged should fail we MUST use our own
heuristics to decide if we should mark the peer as no longer available.
Typically we should allow several failed connection attempts before we decide
to mark the peer as no longer present.</p>
<p>If we have been notified via a networkChanged event that one of Bluetooth or
Wifi are no longer available but not both then this should not cause any
immediate action since MPCF seems able to run exclusively over one transport
or the other.</p>
<p>If however we have been notified via a networkChanged even that both
Bluetooth and Wifi are no longer available then we MUST mark all peers that
we have previously advertised as available as now being unavailable and
advertise this change via the peerAvailabilityChanged event.</p>
<p>If we have been notified via a discoveryAdvertisingStatus event that
discovery is no longer available then we MUST change the availability of
peers discovered via MPCF as not available and advertise this fact via
peerAvailabilityChanged.</p>
<p><strong>Open Issue:</strong> The MPCF explicitly states that one shouldn't keep discovery
on all the time. One suspects this is because they are using Bluetooth for
discovery. As such as may need to cycle discovery on and off to save battery.
In that case we will need to change the logic above so that turning off
discovery doesn't make the peer appear to be gone.</p>
<p>If we have been notified via a discoveryAdvertisingStatus even that
advertising is no longer available then this should not cause any change in
our peer status.</p>
<h2>Wifi</h2><p>In the case of Wifi SSDP supports sending both announcements of
availability as well as announcements that one is going off line. If we
receive an announcement that a peer is going away then we can trust that
since it means the peer is deactivating its SSDP stack. But we can't rely on
receiving such an announcement since obviously if a peer just walks away
nothing will be said. So we MUST set a timer after receiving a SSDP
announcement for a peer (we will receive this via a module:ThaliWifiInfrastructure~wifiPeerAvailabilityChanged event) and if we
don't hear an announcement that they are gone then we MUST automatically
generate such an announcement ourselves.</p>
<p>Unlike the non-TCP transports, we do not use a proxy architecture with Wifi
and therefore do not know if an attempted connection succeeded or not. This
is why there is no equivalent requirement here to the ones above specifying
that failed connections should cause us to mark a peer as not available.</p>
<p>If we have been notified via a networkChanged event that Wifi is no longer
available then all peers discovered via Wifi MUST be marked as not present
and this fact advertised via peerAvailabilityChanged.</p>
<p>If we have been notified via a discoveryAdvertisingStatus event that
discovery is no longer available then we MUST change the availability of
peers discovered via Wifi to not available and advertise this fact via
peerAvailabilityChanged. This is a bit harsh since if Wifi is still working
we certainly could connect to those peers but once discovery is off we have
no way of knowing if the peer has disappeared and since we don't have a proxy
architecture we can't detect failed connections. So it's just easier for now
to just treat the peers as gone.</p>
<p>If we have been notified via a discoveryAdvertisingStatus event that
advertising is no longer available then this should not cause any change in
our peer status.</p>
<h2>General guidelines on handling nonTCPPeerAvailabilityChanged and</h2><p>wifiPeerAvailabilityChanged events</p>
<p>If we receive a <a href="module-thaliMobileNativeWrapper.html#~nonTCPPeerAvailabilityChanged">module:thaliMobileNativeWrapper~nonTCPPeerAvailabilityChanged</a> event then all
we have to do is return the arguments below as taken from the event with the
exception of setting hostAddress to 127.0.0.1 unless the peer is not
available in which case we should set both hostAddress and portNumber to
null.</p>
<p>If we receive a module:ThaliWifiInfrastructure~wifiPeerAvailabilityChanged event then all we
have to do is return the arguments below as taken from the event with the
exception of setting something reasonable for the suggestedTCPTimeout.</p>
</div>
<h5>Type:</h5>
<ul>
<li>
<span class="param-type">Object</span>
</li>
</ul>
<h5 class="subsection-title">Properties:</h5>
<table class="props">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>peerIdentifier</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>This is exclusively used to detect if
this is a repeat announcement or if a peer has gone to correlate it to the
announcement of the peer's presence. But this value is not used to establish
a connection to the peer, the hostAddress and portNumber handle that.</p></td>
</tr>
<tr>
<td class="name"><code>hostAddress</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>The IP/DNS address to connect to or null if
this is an announcement that the peer is no longer available.</p></td>
</tr>
<tr>
<td class="name"><code>portNumber</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last"><p>The port to connect to on the given
hostAddress or null if this is an announcement that the peer is no longer
available.</p></td>
</tr>
<tr>
<td class="name"><code>suggestedTCPTimeout</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last"><p>Provides a hint to what time out to
put on the TCP connection. For some transports a handshake can take quite a
long time.</p></td>
</tr>
<tr>
<td class="name"><code>connectionType</code></td>
<td class="type">
<span class="param-type">connectionTypes</span>
</td>
<td class="description last"><p>Defines the kind of connection
that the request will eventually go over. This information is needed so that
we can better manage how we use the different transport types available to
us.</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliMobile.js.html">NextGeneration/thaliMobile.js</a>, <a href="NextGeneration_thaliMobile.js.html#line190">line 190</a>
</li></ul></dd>
</dl>
</article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Modules</h3><ul><li><a href="module-TCPServersManager.html">TCPServersManager</a></li><li><a href="module-thaliMobile.html">thaliMobile</a></li><li><a href="module-thaliMobileNative.html">thaliMobileNative</a></li><li><a href="module-thaliMobileNativeWrapper.html">thaliMobileNativeWrapper</a></li><li><a href="module-thaliNotificationAction.html">thaliNotificationAction</a></li><li><a href="module-thaliNotificationBeacons.html">thaliNotificationBeacons</a></li><li><a href="module-thaliNotificationClient.html">thaliNotificationClient</a></li><li><a href="module-thaliNotificationServer.html">thaliNotificationServer</a></li><li><a href="module-thaliPeerAction.html">thaliPeerAction</a></li><li><a href="module-thaliPeerDictionary.html">thaliPeerDictionary</a></li><li><a href="module-thaliPeerPoolInterface.html">thaliPeerPoolInterface</a></li><li><a href="module-ThaliWifiInfrastructure.html">ThaliWifiInfrastructure</a></li><li><a href="module-WifiBasedNativeMock.html">WifiBasedNativeMock</a></li></ul><h3>Externals</h3><ul><li><a href="external-_Mobile(_connect_)_.html">Mobile('connect')</a></li><li><a href="external-_Mobile(_discoveryAdvertisingStateUpdateNonTCP_)_.html">Mobile('discoveryAdvertisingStateUpdateNonTCP')</a></li><li><a href="external-_Mobile(_incomingConnectionToPortNumberFailed_)_.html">Mobile('incomingConnectionToPortNumberFailed')</a></li><li><a href="external-_Mobile(_killConnections_)_.html">Mobile('killConnections')</a></li><li><a href="external-_Mobile(_networkChanged_)_.html">Mobile('networkChanged')</a></li><li><a href="external-_Mobile(_peerAvailabilityChanged_)_.html">Mobile('peerAvailabilityChanged')</a></li><li><a href="external-_Mobile(_startListeningForAdvertisements_)_.html">Mobile('startListeningForAdvertisements')</a></li><li><a href="external-_Mobile(_startUpdateAdvertisingAndListening_)_.html">Mobile('startUpdateAdvertisingAndListening')</a></li><li><a href="external-_Mobile(_stopAdvertisingAndListening_)_.html">Mobile('stopAdvertisingAndListening')</a></li><li><a href="external-_Mobile(_stopListeningForAdvertisements_)_.html">Mobile('stopListeningForAdvertisements')</a></li></ul><h3>Classes</h3><ul><li><a href="ConnectionTable.html">ConnectionTable</a></li><li><a href="module-TCPServersManager-TCPServersManager.html">TCPServersManager</a></li><li><a href="module-thaliNotificationAction-NotificationAction.html">NotificationAction</a></li><li><a href="module-thaliNotificationBeacons-ParseBeaconsResponse.html">ParseBeaconsResponse</a></li><li><a href="module-thaliNotificationClient-ThaliNotificationClient.html">ThaliNotificationClient</a></li><li><a href="module-thaliNotificationServer-ThaliNotificationServer.html">ThaliNotificationServer</a></li><li><a href="module-thaliPeerAction-PeerAction.html">PeerAction</a></li><li><a href="module-thaliPeerDictionary-NotificationPeerDictionaryEntry.html">NotificationPeerDictionaryEntry</a></li><li><a href="module-thaliPeerDictionary-PeerConnectionInformation.html">PeerConnectionInformation</a></li><li><a href="module-thaliPeerDictionary-PeerDictionary.html">PeerDictionary</a></li><li><a href="module-thaliPeerPoolInterface-ThaliPeerPoolInterface.html">ThaliPeerPoolInterface</a></li><li><a href="module-ThaliWifiInfrastructure-ThaliWifiInfrastructure.html">ThaliWifiInfrastructure</a></li><li><a href="module-WifiBasedNativeMock-MobileCallInstance.html">MobileCallInstance</a></li><li><a href="module-WifiBasedNativeMock-WifiBasedNativeMock.html">WifiBasedNativeMock</a></li></ul><h3>Events</h3><ul><li><a href="module-thaliMobileNativeWrapper.html#~event:discoveryAdvertisingStateUpdateNonTCPEvent">discoveryAdvertisingStateUpdateNonTCPEvent</a></li><li><a href="module-ThaliWifiInfrastructure.html#~event:discoveryAdvertisingStateUpdateWifiEvent">discoveryAdvertisingStateUpdateWifiEvent</a></li><li><a href="module-TCPServersManager.html#~event:failedConnection">failedConnection</a></li><li><a href="module-thaliMobileNativeWrapper.html#~event:incomingConnectionToPortNumberFailed">incomingConnectionToPortNumberFailed</a></li><li><a href="module-thaliMobileNativeWrapper.html#~event:networkChangedNonTCP">networkChangedNonTCP</a></li><li><a href="module-ThaliWifiInfrastructure.html#~event:networkChangedWifi">networkChangedWifi</a></li><li><a href="module-thaliMobileNativeWrapper.html#~event:nonTCPPeerAvailabilityChangedEvent">nonTCPPeerAvailabilityChangedEvent</a></li><li><a href="module-TCPServersManager.html#~event:routerPortConnectionFailed">routerPortConnectionFailed</a></li><li><a href="module-ThaliWifiInfrastructure.html#~event:wifiPeerAvailabilityChanged">wifiPeerAvailabilityChanged</a></li><li><a href="module-thaliMobile.html#.event:event:discoveryAdvertisingStateUpdate">discoveryAdvertisingStateUpdate</a></li><li><a href="module-thaliMobile.html#.event:event:networkChanged">networkChanged</a></li><li><a href="module-thaliMobile.html#.event:event:peerAvailabilityChanged">peerAvailabilityChanged</a></li><li><a href="module-thaliNotificationAction-NotificationAction.html#.event:event:Resolved">Resolved</a></li><li><a href="module-thaliNotificationClient.html#.event:event:peerAdvertisesDataForUs">peerAdvertisesDataForUs</a></li></ul><h3>Global</h3><ul><li><a href="global.html#getPKCS12Content">getPKCS12Content</a></li><li><a href="global.html#getPublicKeyHash">getPublicKeyHash</a></li><li><a href="global.html#stopThaliReplicationManager">stopThaliReplicationManager</a></li><li><a href="global.html#ThaliEmitter">ThaliEmitter</a></li></ul>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.0</a> on Mon Jan 18 2016 11:19:31 GMT+0200 (EET)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>