Review API pjsua_transport_close()

[nanang]

This API is mainly used for shutting down the transport *listener*, while SIP endpoint applications usually don't need to shutdown a listener, especially if it uses a SIP proxy and/or behind NAT, as it won't need to accept incoming TCP/TLS connection (the connection is always initiated by the endpoint).

Currently, there is a known flaw with this API:

• if 'force' is specified, it is unsafe:

   * Close the transport. If transport is forcefully closed, it will be
   * immediately closed, and any pending transactions that are using the
   * transport may not terminate properly (it may even crash). Otherwise, 
   * the system will wait until all transactions are closed while preventing 
   * new users from using the transport, and will close the transport when 
   * it is safe to do so.
  

• otherwise, it will leak PJSUA transport descriptor, i.e: pjsua_var.tpdata:

   * If force is not specified, transports will be closed at their
   * convenient time. However this will leak PJSUA-API transport
   * descriptors as PJSUA-API wouldn't know when exactly the
   * transport is closed thus it can't cleanup PJSUA transport
   * descriptor.
  

This ticket will review whether the leak issue could be resolved, and in case it couldn't (or perhaps requiring major changes), perhaps we should consider to deprecate the API.

[riza]

TeluuCon? 2018: need to deprecate this API