External: Mobile('StartUpdateAdvertisingAndListenForIncomingConnections')

This method has two separate but related functions. It's first function is to begin advertising the Thali peer's presence to other peers. The second purpose is to accept incoming non-TCP/IP connections (that will then be bridged to TCP/IP) from other peers.

In Android these functions can be separated but with iOS the multi-peer connectivity framework is designed such that it is only possible for remote peers to connect to the current peer if and only if the current peer is advertising its presence. So we therefore have put the two functions together into a single method.

Discovery

Thali currently handles discovery by announcing over the discovery channel that the Thali peer has had a state change without providing any additional information, such as who the peer is or who the state changes are relevant to. The remote peers, when they get the state change notification, will have to connect to this peer in order to retrieve information about the state change.

Therefore the purpose of this method is just to raise the "state changed" flag. Each time it is called a new event will be generated that will tell listeners that the system has changed state since the last call. Therefore this method is not idempotent since each call causes a state change.

Once an advertisement is sent out as a result of calling this method typically any new peers who come in range will be able to retrieve the existing advertisement. So this is not a one time event but rather more of a case of publishing an ongoing advertisement regarding the peer's state.

Incoming Connections

This method also instructs the native layer to accept incoming connections over the non-TCP/IP transport and to bridge those connections to TCP/IP and then connect to the submitted portNumber on 127.0.0.1.

When another device connects to this device over the non-TCP/IP based native technology the native layer will create a local TCP/IP client who will connect to 127.0.0.1 using the supplied portNumber. This will make the remote device look to the local Node.js code as if it were talking over TCP/IP. But this is just a bridge from the non-TCP/IP native technology to TCP/IP.

Repeated calls

By design this method is intended to be called multiple times without calling stop as each call causes the currently notification flag to change. But this method MUST NOT be called with a different portNumber than previous calls unless there was an intervene call to stop. This restriction is just to reduce our test matrix and because it does not interfere with any of our current supported scenarios. If this method is called consecutively without an intervening stop using different portNumbers then the callback MUST return a "No Changing portNumber without a stop" error.