Changes between Initial Version and Version 1 of IPAddressChange-2.7

Timestamp:

Jul 23, 2018 7:49:57 AM (6 years ago)

Author:

riza

Comment:

--

IPAddressChange-2.7

@@ +1 @@
+= 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:
+First, updating 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.
+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 point 2 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]
+
+
+