SDK Termination

This article describes how to terminate the libSoftphone SDK gracefully on Android.

Overview

Termination is the process of cleanly shutting down the SDK — ending all active calls and unregistering all SIP accounts — before the application process exits.

Termination is asynchronous. You request it and receive a callback when the SDK has finished. The application should not exit the process before the callback is invoked.

Requesting Termination

Call Instance.State.requestTermination to start the termination process:

NativeHandle terminationHandle = Instance.State.requestTermination(new OnTerminatedCallback()
{
    @Override
    public void onTerminated()
    {
        // SDK has finished terminating — safe to exit the process
        System.exit(0);
    }
});

Using a lambda (Java 8+):

NativeHandle terminationHandle = Instance.State.requestTermination(() -> System.exit(0));

With a custom timeout

The default timeout is 20 seconds. Pass an explicit timeout in milliseconds when a different value is required:

NativeHandle terminationHandle = Instance.State.requestTermination(10_000L, () -> System.exit(0));

The SDK attempts to complete all termination tasks before the timeout. Once the timeout is reached, the SDK is considered terminated regardless of whether all tasks finished.

The Returned Handle

requestTermination returns a NativeHandle that implements Disposable. You can ignore the return value if you do not need to cancel the termination — the handle will be closed automatically when garbage collected.

If you do need to cancel later, store the handle so you can call dispose() on it:

public class MyApplication extends Application
{
    private NativeHandle mTerminationHandle;

    public void terminate()
    {
        mTerminationHandle = Instance.State.requestTermination(() -> System.exit(0));
    }
}

Cancelling Termination

To cancel an in-progress termination, call dispose() on the handle. The SDK will respawn and resume normal operation:

mTerminationHandle.dispose();
mTerminationHandle = null;

Migrating from the Previous API

The previous Instance.State.terminate() method and TerminateTask helper class have been removed. Replace them with requestTermination:

Old API	New API
Instance.State.terminate()	Instance.State.requestTermination(callback)
new TerminateTask().execute()	Instance.State.requestTermination(callback)

The key difference is that the application now receives an explicit callback instead of polling Instance.State.isTerminated().