API to handle IP address change

[riza]

IP address change and/or access point disconnection and reconnection are scenarios that need to be handled in mobile applications. Few issues or scenarios related to this for example are:

• user moves outside the range of a Wi-Fi access point (AP) and lost the connection
• user moves outside the range of one AP and reconnect to another
• the handset may get new IP address if user reconnects to different AP

This ticket will introduce a new API pjsua_handle_ip_change()/Endpoint::handleIpChange() to handle IP address change. This way, application only needs to detect for IP address change event, and let the library
handle the IP address change based on the configuration.

When invoked, the stack will:

1. Restart the SIP transport listener
   This will restart TCP/TLS listener no matter whether they are enabled or not when the transport were created. If you don't have any use of the listener, you can disable this. However, if you do need this, then on some platform (e.g: on IOS), some delay is needed when restarting the the listener.
   

   pjsua_ip_change_param.restart_listener
      IpChangeParam::restartListener
   pjsua_ip_change_param.restart_lis_delay
      IpChangeParam::restartListener
   

2. Shutdown the SIP transport used by account registration
   On some platform (e.g: iOS), it is necessary to shutdown the transport used by registration, since presumably the socket is already in a bad state.
   

   pjsua_acc_config.ip_change_cfg.shutdown_tp
      AccountIpChangeConfig::shutdownTp
   

3. Update contact URI by sending re-Registration
   The server needs to be updated of the new Contact URI when the IP address changed. Set it to PJ_TRUE to allow the stack update contact URI to the server.
   

   pjsua_acc_config.allow_contact_rewrite
      AccountNatConfig::contactRewriteUse
   pjsua_acc_config.contact_rewrite_method
      AccountNatConfig::contactRewriteMethod
   

4. Hangup active calls or continue the call by sending re-INVITE
   You can either hangup or maintain the ongoing/active calls. If you intend to maintain the active calls, updating dialog's contact URI is required. This can be done by specifying PJSUA_CALL_UPDATE_CONTACT to the reinvite flags.

   pjsua_acc_config.ip_change_cfg.hangup_calls
      AccountIpChangeConfig::hangupCalls
   pjsua_acc_config.ip_change_cfg.reinvite_flags
      AccountIpChangeConfig::reinviteFlags
   

To monitor the progress of IP change handling, application can use on_ip_change_progress()/Endpoint::onIpChangeProgress() callback. The callback will notify application of these events:

• restart SIP transport listener
• shutdown SIP transport
• update contact (re-registration process)
• hangup calls
• re-INVITE calls

[riza]

In 5649:

Re #2041: Implement API to handle IP address change.

[riza]

In 5762:

Fixed #2041: Prevent double free on Failed STUN resolution.

[ming]

Replying to riza:

In 5762:

Fixed #2041: Prevent double free on Failed STUN resolution.

Incorrect ticket number, should be #2104.