= IP Address change handling in 2.7 =

[[PageOutline(2-3,,inline)]]

This article describes some issues and their corresponding solutions related to access point disconnection, reconnection, IP address change, and how to handle these events in your PJSIP applications, specifically 
on 2.7. This is an update to the previous [wiki:IPAddressChange doc] and will focus on the new API {{{pjsua_handle_ip_change()}}}.

[[BR]]

== Problem description ==

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

== IP address change handling using {{{pjsua_handle_ip_change()}}} ==
Since 2.7, pjsua API introduce a new API ({{{pjsua_handle_ip_change()}}}) 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. 

== API ({{{pjsua_handle_ip_change()}}}) flow ==
When invoked, the stack will:
1. Restart the SIP transport listener [[BR]]
   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. [[BR]]
   ref: {{{pjsua_ip_change_param.restart_listener}}} and {{{pjsua_ip_change_param.restart_lis_delay}}}.
2. Shutdown the SIP transport used by account registration [[BR]]
   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. [[BR]]
   ref: {{{pjsua_acc_config.ip_change_cfg.shutdown_tp}}}.
3. Update contact URI by sending re-Registration [[BR]]
   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. [[BR]] 
   ref: {{{pjsua_acc_config.allow_contact_rewrite}}} and {{{pjsua_acc_config.contact_rewrite_method}}}.
4. Hangup active calls or continue the call by sending re-INVITE [[BR]]
   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. Note that, hanging up calls might be inevitable on some cases, please see [wiki:IPv6#NetworkchangetoadifferentIPaddresstype.IPv4toIPv6orIPv6toIPv4 below] [[BR]]
   ref: {{{pjsua_acc_config.ip_change_cfg.hangup_calls}}} and {{{pjsua_acc_config.ip_change_cfg.reinvite_flags}}}.

== Notes and limitations ==
To monitor the progress of IP change handling, application can use on_ip_change_progress() 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
Related to maintaining a call during IP change, there are some scenarios that are currently not implemented by IP change mechanism, so application needs to handle manually:
If IP change occurs during SDP negotiation (and it is not completed yet, so there cannot be another SDP offer), updating such call needs to be done in two steps:
1. Update Contact header, so remote endpoint can send its SDP answer to our new contact address, i.e: use UPDATE without SDP offer ({{{PJSUA_CALL_NO_SDP_OFFER}}} flag). Note that, not every endpoint supports UPDATE. Contact is used by remote to 
   resolve target before sending new requests. If proxy is used, then you can probably skip this.
2. Update local media transport after SDP answer is received, by sending UPDATE/re-INVITE with {{{PJSUA_CALL_REINIT_MEDIA}}} flag.

If IP change occurs before a call is established, there are two possible cases:
Dialog is not yet created, since response with To tag is not received yet. The call needs to be cleared and reported to application via {{{on_call_state().}}}
Dialog is created, (1xx response with To tag is received).
 - SDP nego is done, then update Contact and SDP is needed using re-INVITE or UPDATE.
 - SDP nego is not done, see the steps above.




== IP change scenarios ==

=== Network change to the same IP address type. (IPv4 to IPv4) or (IPv6 to IPv6) ===

   Update contact process (re-Registration) and call handling (hang-up or continue the call) should be handled by the API ({{{pjsua_handle_ip_change()}}}) without any special treatment from the application. 

=== Network change to a different IP address type. (IPv4 to IPv6) or (IPv6 to IPv4) ===

   As you already know, IPv6 needs specific account configuration as described [wiki:IPv6 here].
   On the case of IP address type change, then additional steps are required from application.

   a) Once application detects a network with IP address type change, a new transport might need to be created.

   b) Once the transport is available, app can change the account configuration needed for IPv6/IPv4 and call {{{pjsua_handle_ip_change()}}}.

   Notes: to maintain ongoing calls, update to RTP/RTCP address and update dialog’s Contact is needed using re-INVITE. However sending re-INVITE might fail when route set is still using IPv4 (e.g: Record-route returned contains IPv4).
In this case, forcefully disconnect the call is recommended. 

{{{
static void ip_change_to_ip6()
{
   ...
   //create new ipv6 transport, if it's not yet available. e.g: UDP6
   status = pjsua_transport_create(PJSIP_TRANSPORT_UDP6,
				   &udp_cfg,
				   &transport_id);
   ...
   // modify specific IPv6 account configuration
   pjsua_acc_get_config(acc_id, app_config.pool, &acc_cfg);
   acc_cfg.ipv6_media_use = PJ_TRUE;
   pjsua_acc_set_transport(acc_id, transport_id);
   acc_cfg.ip_change_cfg.hangup_calls = PJ_TRUE;	
   pjsua_acc_modify(acc_id, &acc_cfg);

   ...
   // handle ip change
   pjsua_ip_change_param_default(&param);
   pjsua_handle_ip_change(param);
}

}}}

== IP address change detection ==
=== iOS ===
Have a look at [https://developer.apple.com/library/content/samplecode/Reachability/Introduction/Intro.html Reachability API]

=== Android ===
Have a look at [https://developer.android.com/training/monitoring-device-state/connectivity-monitoring.html ConnectivityManager]