SIP Instance Server =================== .. contents:: :local: :depth: 3 The SIP Instance Server (SIPIS) is Acrobits’ workaround for app background work restrictions employed in modern mobile operating systems (iOS and Android). These restrictions help modern devices to conserve their battery to the maximum, but apps running on such devices cannot access network and cannot fully utilize the CPU when the app is not visible on the screen, making it impossible to maintain SIP registration and receive incoming calls when the app is not in use. Apple’s answer to the above and similar issues was the introduction of the Apple Push Notification Service (APNS). Google has a similar service too - Firebase Cloud Messaging. Basically, one can send a chunk of data to Apple/Google and Apple/Google will forward it, at its own discretion, to a particular device, based on the device’s unique identifier. The device may then display a simple message box, allowing the user to start an application which can further process the push notification. Unfortunately, nor APNS nor Firebase alone doesn’t really solve the incoming call problem as a SIP softphone must periodically refresh its registration on the registrar server to be able to receive and answer incoming calls. Therefore, to receive an incoming SIP call on the mobile device at any time, there must be an entity which maintains the SIP registration on behalf of the device. This entity is the SIP Instance Server -– it registers on behalf of the device and when incoming call arrives it notifies the user’s device via APNS or Firebase. Now we are almost done. The only remaining problem is how to patch the incoming call through to the device. This turned out to be the most difficult problem. In the end we ended up with the following method which puts SIPIS to the role of an active relay. When a device receives a push notification about a pending incoming call, it launches the softphone application. The softphone creates a special SIP user agent which communicates directly with SIPIS. Next, the softphone notifies SIPIS about its “readiness” and SIPIS then proceeds by initiating its own SIP call with the device. This new call is constructed using most of the information from the real incoming call, so from the mobile device point of view it just seems as if the call came directly from the calling party (while it is, in fact, just a “tunnel” between the device and SIPIS). Once this new call is established, SIPIS relays all relevant signaling information between these two separate calls. Note that while SIP signaling goes always through the SIPIS, RTP media streams don’t. .. note:: SIPIS is provided for Cloud Softphone and SDK users. If you are running Acrobits Groundwire or Acrobits Softphone, your app is configured to use Acrobits' SIPIS servers for free. SIPIS Ecosystem --------------- The following diagram illustrates the SIPIS ecosystem with the SIPIS Installation placed inside the VoIP provider's perimeter. .. figure:: overview_ecosystem.png SIPIS Ecosystem For its full functionality, SIPIS relies on the following external services. PostgreSQL Server ................. SIPIS uses this database to obtain the information necessary for a successful registration on behalf of the softphone users. The database also serves as a persistent data backend. Push Notification Mediator ........................... Internally, SIPIS uses proprietary unified push notification protocol. It is the task of the Push Notification Mediator, to transform incoming push notifications to the appropriate format for a given platform and relay them to the platform specific push notification service. TLS, TCP to UDP Bridge + Load Balancer ...................................... SIPIS itself handles all communication with the softphone via the UDP protocol. To allow the softphone to communicate with SIPIS using the TCP and TLS protocols, we decided to build this small utility program that translates TCP and TLS traffic to corresponding UDP traffic and vice versa. Optionally, this program can be configured to distribute server load to multiple SIPIS servers -- each one dedicated to a portion of the entire user space.