Skip to content

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

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 ->
                context.applicationContext.packageManager
                    ?.getLaunchIntentForPackage(context.applicationContext.packageName)
                    ?.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:
                        //
                        // https://medium.com/swlh/truly-understand-tasks-and-back-stack-intent-flags-of-activity-2a137c401eca

                        builder.setContentIntent(
                            PendingIntent.getActivity(
                                context.applicationContext,
                                0, // Your desired request code
                                intent,
                                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 ) {
        TorServiceController.Builder(
            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())

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

            .build()
//  }

Parameters

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”)

Constructors

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)

Functions

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 exceptions.fun 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 out.fun 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 App.fun setEventBroadcaster(eventBroadcaster:TorServiceEventBroadcaster): 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 TorConfigFiles.createConfig.fun useCustomTorConfigFiles(torConfigFiles:TorConfigFiles): Builder