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 — attempting to end all active calls and unregister all SIP accounts — before the application process exits.

The shutdown process also synchronizes registration state with SIPIS. When an account is deleted before termination as part of logout, this synchronization deletes the corresponding SIPIS instance.

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:

private NativeHandle terminationHandle;

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+):

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. Store the handle and keep it alive through the callback and for as long as the SDK must remain terminated. Disposing or releasing it before completion cancels the request and can prevent termination from completing; releasing it after completion respawns the SDK.

public class MyApplication extends Application
{
    private NativeHandle mTerminationHandle;

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

Releasing the Handle Before Completion

Calling dispose() on the handle cancels an in-progress request:

mTerminationHandle.dispose();
mTerminationHandle = null;

Do not use this as the normal way to resume SDK processing. Retain the handle through the callback, then explicitly respawn the SDK as described below.

Using the SDK Again

If termination has completed and the process remains open, keep the handle alive for as long as the SDK should stay terminated. To use the SDK again, call Instance.State.respawn() before releasing the handle:

Instance.State.respawn();
mTerminationHandle.dispose();
mTerminationHandle = null;

The callback runs when cleanup finishes or the timeout is reached. If remote PBX or SIPIS contacts remain after a timeout, they can persist until their registration expires.

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().