Background

Currently this is how the media channel interacts with SIP call in PJSUA-LIB:

pjsua_call_make_call():
pjsua_call_on_incoming():
pjsua_call_update():
pjsua_call_reinvite():
pjsua_call_on_rx_offer():
pjsua_call_on_create_offer():
{
	pjsua_media_channel_init();
	pjsua_media_channel_create_sdp();
}

pjsua_call_on_media_update():
{
	pjsua_media_channel_update();
}

pjsua_call_on_state_changed(DISCONNECTED):
pjsua_call_on_media_update(HOLD):
{
	pjsua_media_channel_deinit();
}

and this is the implementation of media channel functions above:

pjsua_media_channel_init()
{
	pjmedia_transport_srtp_create();
}

pjsua_media_channel_create_sdp():
{
	pjmedia_endpt_create_sdp();
	pjmedia_transport_media_create();
}

pjsua_media_channel_update():
{
	pjmedia_transport_media_start();
	pjmedia_session_create();
}

pjsua_media_channel_deinit():
{
	stop_media_session();
	pjmedia_transport_media_stop();
	pjmedia_transport_close(srtp);
}

Reasons for Fix/Change?

The interface above has some drawbacks:

1. The main drawback is it does not distinguish between a new/freshly created call and existing call (which needs updating the media because of re-INVITE/UPDATE), functions such as pjsua_call_on_create_offer() will actually re-initialize the media, hence causing problems such as ticket #525 (crash on UPDATE/re-INVITE).
2. It requires media transports to be re-created during application startup and kept-alive throughout the application lifetime. The drawbacks of this are (as documented by ticket #539):
   1. it requires STUN and TURN transport to be kept-alive, which means it needs to send periodic keep-alive packets, and this is not good for battery consumption in mobile devices.
   2. it requires TURN long-term allocation, which will fail if the NAT/mapped public IP address mapping has changed.
   3. even when TURN is not used it may still fail when normal UDP media transport (i.e. not ICE) is used and the IP address (STUN or not) changes.
   4. it allocates a lot of resources when the number of max_calls is large.

New Design Specification

Distinguish Between Fresh Call and UPDATE/re-INVITE

pjsua_call_make_call():
pjsua_call_on_incoming():
{
	pjsua_media_channel_init();
	pjsua_media_channel_create_sdp();
}

pjsua_call_update():
pjsua_call_reinvite():
pjsua_call_on_rx_offer():
pjsua_call_on_create_offer():
{
	if (media==NULL)
           pjsua_media_channel_init();
	pjsua_media_channel_create_sdp();
}

pjsua_call_on_media_update():
{
	pjsua_media_channel_update();
}

pjsua_call_on_state_changed(DISCONNECTED):
pjsua_call_on_media_update(HOLD):
{
	pjsua_media_channel_deinit();
}

pjsua_media_channel_init()
{
	pjmedia_transport_srtp_create();
}

pjsua_media_channel_create_sdp():
{
	pjmedia_endpt_create_sdp();
	pjmedia_transport_media_create();
}

pjsua_media_channel_update():
{
	pjmedia_transport_media_start();
	pjmedia_session_create();
}

pjsua_media_channel_deinit():
{
	stop_media_session();
	pjmedia_transport_media_stop();
	pjmedia_transport_close(srtp);
}

Create Media Transport On-Demand

Media transport (including SRTP) will be created before call.