thali

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>JSDoc: External: Mobile('connect')</title> <script src="scripts/prettify/prettify.js"> </script> <script src="scripts/prettify/lang-css.js"> </script>  <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">External: Mobile('connect')</h1> <section> <header> <h2> <span class="ancestors"><a href="module-thaliMobileNative.html">thaliMobileNative</a>~</span>Mobile('connect')</h2> </header> <article> <div class="container-overview"> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="NextGeneration_thaliMobileNative.js.html">NextGeneration/thaliMobileNative.js</a>, <a href="NextGeneration_thaliMobileNative.js.html#line206">line 206</a> </li></ul></dd> </dl> </div> <h3 class="subsection-title">Methods</h3> <h4 class="name" id=".callNative"><span class="type-signature">(static) </span>callNative<span class="signature">(peerIdentifier, callback)</span><span class="type-signature"></span></h4> <div class="description"> <p>This method tells the native layer to establish a non-TCP/IP connection to the identified peer and to then create a TCP/IP bridge on top of that connection which can be accessed locally by opening a TCP/IP connection to the port returned in the callback.</p> <p>This method MUST return an error if called while start listening for advertisements is not active. This restriction is really only needed for iOS but we enforce it on Android as well in order to keep the platform consistent.</p> <p>If this method is called consecutively with the same peerIdentifier then if a connection already exists its port MUST be returned otherwise a new connection MUST be created. In the case of Android there MUST be at most one Bluetooth client connection between this peer and the identified remote peer. In the case of iOS there MUST be at most one MCSession between this peer and the identified remote peer. In the case of iOS if this peer is lexically smaller than the other peer then the iOS layer MUST try to establish a MCSession with the remote peer as a signaling mechanism per the instructions in the binding spec. If an incoming connection is created within a reasonable time period from the lexically larger peer then the system MUST issue a connect callback with listeningPort set to null and clientPort/serverPort set based on the values used when establishing the incoming connection from the remote peer.</p> <p>The port created by a connect call MUST only accept a single TCP/IP connection at a time. Any subsequent TCP/IP connections to the 127.0.0.1 port MUST be rejected.</p> <p>It is implementation dependent if the non-TCP/IP connection that the 127.0.0.1 port will be bound to is created before the callback is called or only when the TCP/IP port is first connected to.</p> <p>If any of the situations listed below occur then the non-TCP/IP connection MUST be fully closed, the existing connection to the 127.0.0.1 port (if any) MUST be closed and the port MUST be released:</p> <ul> <li>The TCP/IP connection to the 127.0.0.1 port is closed or half closed</li> <li>No connection is made to the 127.0.0.1 port within a fixed period of time, typically 2 seconds (this only applies on Android and for lexically larger iOS peers)</li> <li>If the non-TCP/IP connection should fail in whole or in part (e.g. some non-TCP/IP transports have the TCP/IP equivalent of a 1/2 closed connection)</li> </ul> <p>A race condition exists that can cause something called a "channel binding problem". This race condition occurs when a callback to this method is received with a port but before the port can be used it gets closed and re-assign to someone else. The conditions under which this occur typically involve interactions with the native system and other parallel threads/processes. But if this happens then the client code can think that a certain port represents a particular peer when it may not.</p> <p>Typically we use TLS to address this problem for connections run on the multiplexer layer that sits on top of the port returned by this method. TLS allows us to authenticate that we are talking with whom we think we are talking. But if TLS can't be used then some equivalent mechanism must be or an impersonation attack becomes possible.</p> <table> <thead> <tr> <th>Error String</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>Illegal peerID</td> <td>The peerID has a format that could not have been returned by the local platform</td> </tr> <tr> <td>startListeningForAdvertisements is not active</td> <td>Go start it!</td> </tr> <tr> <td>Connection could not be established</td> <td>The attempt to connect to the peerID failed. This could be because the peer is gone, no longer accepting connections or the radio stack is just horked.</td> </tr> <tr> <td>Connection wait timed out</td> <td>This is for the case where we are a lexically smaller peer and the lexically larger peer doesn't establish a connection within a reasonable period of time.</td> </tr> <tr> <td>Max connections reached</td> <td>The native layers have practical limits on how many connections they can handle at once. If that limit has been reached then this error is returned. The only action to take is to wait for an existing connection to be closed before retrying.</td> </tr> <tr> <td>No Native Non-TCP Support</td> <td>There are no non-TCP radios on this platform.</td> </tr> <tr> <td>Radio Turned Off</td> <td>The radio(s) needed for this method are not turned on.</td> </tr> <tr> <td>Unspecified Error with Radio infrastructure</td> <td>Something went wrong with the radios. Check the logs.</td> </tr> </tbody> </table> </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>peerIdentifier</code></td> <td class="type"> <span class="param-type">string</span> </td> <td class="description last"></td> </tr> <tr> <td class="name"><code>callback</code></td> <td class="type"> <span class="param-type"><a href="module-thaliMobileNative.html#~ConnectCallback">module:thaliMobileNative~ConnectCallback</a></span> </td> <td class="description last"><p>Returns an error or the 127.0.0.1 port to connect to in order to get a connection to the remote peer</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_thaliMobileNative.js.html">NextGeneration/thaliMobileNative.js</a>, <a href="NextGeneration_thaliMobileNative.js.html#line210">line 210</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>