thali
Version:
715 lines (275 loc) • 20.2 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Class: ThaliNotificationClient</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">Class: ThaliNotificationClient</h1>
<section>
<header>
<h2>
<span class="ancestors"><a href="module-thaliNotificationClient.html">thaliNotificationClient</a>~</span>ThaliNotificationClient</h2>
</header>
<article>
<div class="container-overview">
<h4 class="name" id="ThaliNotificationClient"><span class="type-signature"></span>new ThaliNotificationClient<span class="signature">(thaliPeerPool, ecdhForLocalDevice, addressBookCallback)</span><span class="type-signature"></span></h4>
<div class="description">
<p>Creates a class that can register to receive the <a href="module-thaliMobile.html#.event:event:peerAvailabilityChanged">module:thaliMobile.event:peerAvailabilityChanged</a> event. It will listen for
the event and upon receiving it, will enqueue an action with the
submitted thaliPeerPool. Once called back by the pool then the callback will
issue a HTTP GET request to retrieve the notification beacons for the peer,
parse them, see if one matches and if so then fire a <a href="module-thaliNotificationClient.html#.event:event:peerAdvertisesDataForUs">module:thaliNotificationClient.event:peerAdvertisesDataForUs</a>. Callers can
listen for the event by using the emitter member.</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>thaliPeerPool</code></td>
<td class="type">
<span class="param-type"><a href="module-thaliPeerPoolInterface-ThaliPeerPoolInterface.html">module:thaliPeerPoolInterface~ThaliPeerPoolInterface</a></span>
</td>
<td class="description last"><p>Requests to retrieve notification beacons are enqueued on this object in
order to make sure we don't overwhelm our bandwidth or native communication
capabilities.</p></td>
</tr>
<tr>
<td class="name"><code>ecdhForLocalDevice</code></td>
<td class="type">
<span class="param-type">Crypto.ECDH</span>
</td>
<td class="description last"><p>A Crypto.ECDH object initialized
with the local device's public and private keys.</p></td>
</tr>
<tr>
<td class="name"><code>addressBookCallback</code></td>
<td class="type">
<span class="param-type">addressBookCallback</span>
</td>
<td class="description last"><p>An object used to validate
which peers we are interested in talking to.</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_thaliNotificationClient.js.html">NextGeneration/thaliNotificationClient.js</a>, <a href="NextGeneration_thaliNotificationClient.js.html#line30">line 30</a>
</li></ul></dd>
</dl>
<h5>Fires:</h5>
<ul>
<li><a href="module-thaliNotificationClient.html#.event:event:peerAdvertisesDataForUs">module:thaliNotificationClient.event:peerAdvertisesDataForUs</a></li>
</ul>
</div>
<h3 class="subsection-title">Members</h3>
<h4 class="name" id=".ACTION_TYPE"><span class="type-signature">(static, readonly) </span>ACTION_TYPE<span class="type-signature"> :string</span></h4>
<div class="description">
<p>This is the action type that will be used by instances of this class when
registering with <a href="module-thaliPeerPoolInterface-ThaliPeerPoolInterface.html">module:thaliPeerPoolInterface~ThaliPeerPoolInterface</a>.</p>
</div>
<h5>Type:</h5>
<ul>
<li>
<span class="param-type">string</span>
</li>
</ul>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliNotificationClient.js.html">NextGeneration/thaliNotificationClient.js</a>, <a href="NextGeneration_thaliNotificationClient.js.html#line173">line 173</a>
</li></ul></dd>
</dl>
<h4 class="name" id="peerDictionary"><span class="type-signature"></span>peerDictionary<span class="type-signature"> :ThaliNotificationClient.PeerDictionary</span></h4>
<div class="description">
<p>A dictionary used to track the state of peers we have received notifications
about from <a href="module-thaliMobile.html">module:thaliMobile</a>.</p>
</div>
<h5>Type:</h5>
<ul>
<li>
<span class="param-type">ThaliNotificationClient.PeerDictionary</span>
</li>
</ul>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliNotificationClient.js.html">NextGeneration/thaliNotificationClient.js</a>, <a href="NextGeneration_thaliNotificationClient.js.html#line43">line 43</a>
</li></ul></dd>
</dl>
<h3 class="subsection-title">Methods</h3>
<h4 class="name" id="start"><span class="type-signature"></span>start<span class="signature">()</span><span class="type-signature"></span></h4>
<div class="description">
<p>This method will cause a listener to be registered on the global singleton
<a href="module-thaliMobile.html">module:thaliMobile</a> object for the <a href="module-thaliMobile.html#.event:event:peerAvailabilityChanged">module:thaliMobile.event:peerAvailabilityChanged</a> event.</p>
<p>This method MUST be idempotent so calling it twice in a row MUST NOT cause
multiple listeners to be registered with thaliMobile.</p>
<h3>Handling peerAvailabilityChanged Events</h3><p>The notification code is triggered via peerAvailabilityChanged events. In
handling these events remember that our goal is to find the notification
beacons associated with each peerIdentifier. Once we have retrieved the
beacons for a specific peerIdentifier we don't ever need to deal with that
specific peerIdentifier again. If the peer behind the identifier changes
their beacons then we will get a new peerIdentifier.</p>
<ul>
<li>If hostAddress != null<ul>
<li>If this peer is not in the dictionary<ul>
<li>Create a <a href="module-thaliNotificationAction-NotificationAction.html">module:thaliNotificationAction~NotificationAction</a> and
then call enqueue on the submitted <a href="module-thaliPeerPoolInterface-ThaliPeerPoolInterface.html">module:thaliPeerPoolInterface~ThaliPeerPoolInterface</a> object and then
create a new PeerDictionaryEntry object with the peerState set to
enqueued, the peerConnectionDictionary set to a single entry matching the
data in the peerAvailabilityChanged event and the notificationAction set
to the previously created notificationAction object.</li>
</ul>
</li>
<li>If this peer is in the table<ul>
<li>If this peer has been marked as RESOLVED<ul>
<li>Ignore the event</li>
</ul>
</li>
<li>If this peer has been marked as CONTROLLED_BY_POOL and the action's
state is QUEUED or if the peer's state is WAITING<ul>
<li>First update the connection dictionary for the peer's entry with the
new data. Then if the connectionType of the new event is TCP_NATIVE and
if the connectionType of the existing action isn't that then kill the
existing action using <a href="module-thaliPeerPoolInterface-ThaliPeerPoolInterface.html#kill">module:thaliPeerPoolInterface~ThaliPeerPoolInterface#kill</a> and create a
new action and enqueue it and update the entry. The point of this
exercise is that we prefer native TCP transport to other options.</li>
</ul>
</li>
<li>If this peer has been marked as CONTROLLED_BY_POOL and the action's
state is STARTED<ul>
<li>If the connectionType of the event is different than the
connectionType of the action then just update the
peerConnectionDictionary and move on. If the connectionTypes are
identical then kill the existing action as above. If the
peerConnectionDictionary contains a TCP_NATIVE entry then create and
enqueue an action for that. Otherwise take the entry that was just
updated and create and enqueue that as an action.</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li>If hostAddress == null<ul>
<li>If this peer is not in the table<ul>
<li>This is technically possible in a number of cases. If this happens
then just ignore the event.</li>
</ul>
</li>
<li>If this peer is in the table<ul>
<li>If this peer has been marked as resolved<ul>
<li>Ignore the event.</li>
</ul>
</li>
<li>If this peer has been marked as CONTROLLED_BY_POOL and the action's
state is QUEUED or if the peer's state is WAITING or if this peer has
been marked as CONTROLLED_BY_POOL and the action's state is STARTED<ul>
<li>Call kill on the action via <a href="module-thaliPeerPoolInterface-ThaliPeerPoolInterface.html#kill">module:thaliPeerPoolInterface~ThaliPeerPoolInterface#kill</a> and remove
the associated entry in peerConnectionDictionary. If this leaves no
entries in peerConnectionDictionary then remove this table entry in
total from the dictionary. If there is still an entry left then create
a notificationAction for it and enqueue it.</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<h2>Handling Resolved events from notificationActions</h2><p>When creating a notificationAction a listener MUST be placed on that action
to listen for the
<a href="module-thaliNotificationAction-NotificationAction.html#.event:event:Resolved">module:thaliNotificationAction~NotificationAction.event:Resolved</a>
event.</p>
<ul>
<li>BEACONS_RETRIEVED_AND_PARSED<ul>
<li>Mark the entry in the dictionary as RESOLVED and fire
<a href="module-thaliNotificationClient.html#.event:event:peerAdvertisesDataForUs">module:thaliNotificationClient.event:peerAdvertisesDataForUs</a></li>
</ul>
</li>
<li>BEACONS_RETRIEVED_BUT_BAD<ul>
<li>This indicates a malfunctioning peer. We need to assume they are bad all
up and mark their entry as RESOLVED without taking any further action. This
means we will ignore this peerIdentifier in the future.</li>
</ul>
</li>
<li>HTTP_BAD_RESPONSE<ul>
<li>This tells us that the peer is there but not in good shape. But we will
give them the benefit of the doubt. We will wait 100 ms if we are in the
foreground and 500 ms if we are in the background (the later only applies
to Android) and then create a new action (remember, prefer TCP_NATIVE) and
then enqueue it. Make sure to set the dictionary entry's state to
WAITING and when the timer is up and we enqueue to CONTROLLED_BY_POOL.</li>
</ul>
</li>
<li>NETWORK_problem<ul>
<li>Treat the same as HTTP_BAD_RESPONSE</li>
</ul>
</li>
<li>KILLED<ul>
<li>We MUST check the value of the notificationAction on the associated
dictionary entry with the notificationAction that this handler was created
on. If they are different then this means that this class was the one who
called kill and so we can ignore this event. If they are the same then it
means that the ThaliPeerPoolInterface called kill (due to resource
exhaustion). Having the pool kill us is a pretty extreme event, it means
we have so many peerIdentifiers that we blew up the pool. So at that point
the best thing for us to do is to just delete the entire entry for this
peerIdentifier and move on.</li>
</ul>
</li>
</ul>
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliNotificationClient.js.html">NextGeneration/thaliNotificationClient.js</a>, <a href="NextGeneration_thaliNotificationClient.js.html#line145">line 145</a>
</li></ul></dd>
</dl>
<h4 class="name" id="stop"><span class="type-signature"></span>stop<span class="signature">()</span><span class="type-signature"></span></h4>
<div class="description">
<p>Will remove the listener registered on the global thaliMobile object, if
any. This method MUST be idempotent so calling it multiple times MUST only
cause a single call to removeListener on thaliMobile and only then if there
already was a call to addListener on this object.</p>
<p>Removing the listener MUST not just stop listening for the event but MUST
also cause all non-resolved entries in the dictionary to either stop
waiting or if under control of the pool to be killed and then their entries
MUST be removed from the peer dictionary.</p>
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="NextGeneration_thaliNotificationClient.js.html">NextGeneration/thaliNotificationClient.js</a>, <a href="NextGeneration_thaliNotificationClient.js.html#line162">line 162</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:32 GMT+0200 (EET)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>