Skip to content

topl-service / io.matthewnelson.topl_service / TorServiceController / Builder


class Builder (source)

The TorServiceController.Builder is where you get to customize how TorService works for your application. Call it in Application.onCreate and follow along.

//  private fun generateTorServiceNotificationBuilder(context: Context): ServiceNotification.Builder {
        return ServiceNotification.Builder(
            channelName = "TOPL-Android Demo",
            channelDescription = "TorOnionProxyLibrary-Android Demo",
            channelID = "TOPL-Android Demo",
            notificationID = 615
            .setImageTorNetworkingEnabled(drawableRes = R.drawable.tor_stat_network_enabled)
            .setImageTorNetworkingDisabled(drawableRes = R.drawable.tor_stat_network_disabled)
            .setImageTorDataTransfer(drawableRes = R.drawable.tor_stat_network_dataxfer)
            .setImageTorErrors(drawableRes = R.drawable.tor_stat_notifyerr)
            .setVisibility(visibility = NotificationCompat.VISIBILITY_PRIVATE)
            .setCustomColor(colorRes = R.color.primaryColor)
            .enableTorRestartButton(enable = true)
            .enableTorStopButton(enable = true)
            .showNotification(show = true)

            // Set the notification's contentIntent for when the user clicks the notification
            .also { builder ->
                    ?.let { intent ->

                        // Set in your manifest for the launch activity so the intent won't launch
                        // a new activity over top of your already created activity if the app is
                        // open when the user clicks the notification:
                        // android:launchMode="singleInstance"
                        // For more info on launchMode and Activity Intent flags, see:

                                0, // Your desired request code
                                0 // flags
                            // can also include a bundle if desired
//  }
//  private fun generateBackgroundManagerPolicy(): BackgroundManager.Builder.Policy {
        return BackgroundManager.Builder()

            // All available options present. Only 1 is able to be chosen.
            .respectResourcesWhileInBackground(secondsFrom5To45 = 20)
            //.runServiceInForeground(killAppIfTaskIsRemoved = true)
//  }
//  private fun setupTorServices(application: Application, torConfigFiles: TorConfigFiles ) {
            application = application,
            torServiceNotificationBuilder = generateTorServiceNotificationBuilder(application),
            backgroundManagerPolicy = generateBackgroundManagerPolicy(),
            buildConfigVersionCode = BuildConfig.VERSION_CODE,

            // Can instantiate directly here then access it from
            // TorServiceController.Companion.getTorSettings() and cast what's returned
            // as MyTorSettings
            defaultTorSettings = MyTorSettings(),

            // These should live somewhere in your module's assets directory,
            // ex: my-project/my-application-module/src/main/assets/common/geoip
            // ex: my-project/my-application-module/src/main/assets/common/geoip6
            geoipAssetPath = "common/geoip",
            geoip6AssetPath = "common/geoip6"
            .addTimeToDisableNetworkDelay(milliseconds = 1_000L)
            .addTimeToRestartTorDelay(milliseconds = 100L)
            .addTimeToStopServiceDelay(milliseconds = 100L)
            .disableStopServiceOnTaskRemoved(disable = false)
            .setBuildConfigDebug(buildConfigDebug = BuildConfig.DEBUG)

            // Can instantiate directly here then access it from
            // TorServiceController.Companion?.appEventBroadcaster and cast what's returned
            // as MyEventBroadcaster
            .setEventBroadcaster(eventBroadcaster = MyEventBroadcaster())
            .setServiceExecutionHooks(executionHooks = MyServiceExecutionHooks())

            // Only needed if you wish to customize the directories/files used by Tor if
            // the defaults aren't to your liking.
            .useCustomTorConfigFiles(torConfigFiles = torConfigFiles)

//  }


application - Application, for obtaining context

torServiceNotificationBuilder - The ServiceNotification.Builder for customizing TorService‘s notification

backgroundManagerPolicy - The BackgroundManager.Builder.Policy to be executed while your application is in the background (the Recent App’s tray).

buildConfigVersionCode - send BuildConfig.VERSION_CODE. Mitigates copying of geoip files to app updates only

defaultTorSettings - ApplicationDefaultTorSettings used to create your torrc file on start of Tor

geoipAssetPath - The path to where you have your geoip file located (ex: in assets/common directory, send this variable “common/geoip”)

geoip6AssetPath - The path to where you have your geoip6 file located (ex: in assets/common directory, send this variable “common/geoip6”)


Name Summary
<init> The TorServiceController.Builder is where you get to customize how TorService works for your application. Call it in Application.onCreate and follow along.Builder(application:Application, torServiceNotificationBuilder: Builder, backgroundManagerPolicy: Policy, buildConfigVersionCode:Int, defaultTorSettings:ApplicationDefaultTorSettings, geoipAssetPath:String, geoip6AssetPath:String)


Name Summary
addTimeToDisableNetworkDelay Default is set to 6_000ms, (what this method adds time to).fun addTimeToDisableNetworkDelay(milliseconds:Long): Builder
addTimeToRestartTorDelay Default is set to 500ms, (what this method adds time to).fun addTimeToRestartTorDelay(milliseconds:Long): Builder
addTimeToStopServiceDelay Default is set to 100ms (what this method adds time to).fun addTimeToStopServiceDelay(milliseconds:Long): Builder
build Initializes TorService setup and enables the ability to call methods from the Companion object w/o throwing build():Unit
disableStopServiceOnTaskRemoved When your task is removed from the Recent App’s tray, TorService.onTaskRemoved is triggered. Default behaviour is to stop Tor, and then TorService. Electing this option will inhibit the default behaviour from being carried disableStopServiceOnTaskRemoved(disable:Boolean= true): Builder
setBuildConfigDebug This makes it such that on your Application’s Debug builds, the topl-core and topl-service modules will provide you with Logcat messages (when TorSettings.hasDebugLogs is enabled).fun setBuildConfigDebug(buildConfigDebug:Boolean): Builder
setEventBroadcaster Get broadcasts piped to your Application to do with them what you desire. What you send this will live at Companion.appEventBroadcaster for the remainder of your application’s lifecycle to refer to elsewhere in your setEventBroadcaster(eventBroadcaster:TorServiceEventBroadcaster): Builder
setServiceExecutionHooks Implement and set hooks to be executed in TorService.onCreate, and ServiceActionProcessor.processServiceAction prior to starting of Tor, and post stopping of setServiceExecutionHooks(executionHooks:ServiceExecutionHooks): Builder
useCustomTorConfigFiles If you wish to customize the file structure of how Tor is installed in your app, you can do so by instantiating your own TorConfigFiles and customizing it via the TorConfigFiles.Builder, or overridden method useCustomTorConfigFiles(torConfigFiles:TorConfigFiles): Builder