add new class that extends capabilities of the EventBroadcaster for updating the application with addresses Tor is operating on

Author: 05nelsonm

topl-service/build.gradle

@@ -44,7 +44,8 @@ dokka {
         includeNonPublic = false
         skipEmptyPackages = true
         samples = [
-                "$rootDir/sampleapp/src/main/java/io/matthewnelson/sampleapp/App.kt".toString()
+                "$rootDir/sampleapp/src/main/java/io/matthewnelson/sampleapp/App.kt".toString(),
+                "$rootDir/sampleapp/src/main/java/io/matthewnelson/sampleapp/MyEventBroadcaster.kt".toString()
         ]
         sourceLink {
             url = "https://github.com/05nelsonm/TorOnionProxyLibrary-Android/blob/master/"

topl-service/src/main/java/io/matthewnelson/topl_service/service/components/onionproxy/TorServiceEventBroadcaster.kt

@@ -0,0 +1,118 @@
+/*
+* TorOnionProxyLibrary-Android (a.k.a. topl-android) is a derivation of
+* work from the Tor_Onion_Proxy_Library project that started at commit
+* hash `74407114cbfa8ea6f2ac51417dda8be98d8aba86`. Contributions made after
+* said commit hash are:
+*
+*     Copyright (C) 2020 Matthew Nelson
+*
+*     This program is free software: you can redistribute it and/or modify it
+*     under the terms of the GNU General Public License as published by the
+*     Free Software Foundation, either version 3 of the License, or (at your
+*     option) any later version.
+*
+*     This program is distributed in the hope that it will be useful, but
+*     WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+*     or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+*     for more details.
+*
+*     You should have received a copy of the GNU General Public License
+*     along with this program. If not, see <https://www.gnu.org/licenses/>.
+*
+* `===========================================================================`
+* `+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++`
+* `===========================================================================`
+*
+* The following exception is an additional permission under section 7 of the
+* GNU General Public License, version 3 (“GPLv3”).
+*
+*     "The Interfaces" is henceforth defined as Application Programming Interfaces
+*     that are publicly available classes/functions/etc (ie: do not contain the
+*     visibility modifiers `internal`, `private`, `protected`, or are within
+*     classes/functions/etc that contain the aforementioned visibility modifiers)
+*     to TorOnionProxyLibrary-Android users that are needed to implement
+*     TorOnionProxyLibrary-Android and reside in ONLY the following modules:
+*
+*      - topl-core-base
+*      - topl-service
+*
+*     The following are excluded from "The Interfaces":
+*
+*       - All other code
+*
+*     Linking TorOnionProxyLibrary-Android statically or dynamically with other
+*     modules is making a combined work based on TorOnionProxyLibrary-Android.
+*     Thus, the terms and conditions of the GNU General Public License cover the
+*     whole combination.
+*
+*     As a special exception, the copyright holder of TorOnionProxyLibrary-Android
+*     gives you permission to combine TorOnionProxyLibrary-Android program with free
+*     software programs or libraries that are released under the GNU LGPL and with
+*     independent modules that communicate with TorOnionProxyLibrary-Android solely
+*     through "The Interfaces". You may copy and distribute such a system following
+*     the terms of the GNU GPL for TorOnionProxyLibrary-Android and the licenses of
+*     the other code concerned, provided that you include the source code of that
+*     other code when and as the GNU GPL requires distribution of source code and
+*     provided that you do not modify "The Interfaces".
+*
+*     Note that people who make modified versions of TorOnionProxyLibrary-Android
+*     are not obligated to grant this special exception for their modified versions;
+*     it is their choice whether to do so. The GNU General Public License gives
+*     permission to release a modified version without this exception; this exception
+*     also makes it possible to release a modified version which carries forward this
+*     exception. If you modify "The Interfaces", this exception does not apply to your
+*     modified version of TorOnionProxyLibrary-Android, and you must remove this
+*     exception when you distribute your modified version.
+* */
+package io.matthewnelson.topl_service.service.components.onionproxy
+
+import io.matthewnelson.topl_core_base.EventBroadcaster
+
+/**
+ * Adds broadcasting methods to the [EventBroadcaster] to update you with information about
+ * what addresses Tor is operating on. Very helpful when choosing "auto" in your
+ * [io.matthewnelson.topl_core_base.TorSettings] to easily identifying what addresses to
+ * use for making network calls, as well as being notified when Tor is ready to be used.
+ *
+ * The addresses will be broadcast to you after Tor has been fully Bootstrapped. If Tor is
+ * stopped (ie. it's [io.matthewnelson.topl_core_base.BaseConsts.TorState] changes from **ON**
+ * to **OFF**), `null` will be broadcast.
+ *
+ * All broadcasts to your implementation to this class will occur on the Main thread.
+ *
+ * @sample [io.matthewnelson.sampleapp.MyEventBroadcaster]
+ * */
+abstract class TorServiceEventBroadcaster: EventBroadcaster() {
+
+    /**
+     * Override this method to implement receiving of the control port address that Tor
+     * is operating on.
+     *
+     * Example of what will be broadcast:
+     *
+     *   - "127.0.0.1:33432"
+     * */
+    abstract fun broadcastControlPortAddress(controlPortAddress: String?)
+
+    /**
+     * Override this method to implement receiving of the Socks port address that Tor
+     * is operating on (if you've specified a
+     * [io.matthewnelson.topl_core_base.TorSettings.socksPort]).
+     *
+     * Example of what will be broadcast:
+     *
+     *   - "127.0.0.1:9051"
+     * */
+    abstract fun broadcastSocksPortAddress(socksPortAddress: String?)
+
+    /**
+     * Override this method to implement receiving of the http port address that Tor
+     * is operating on (if you've specified a
+     * [io.matthewnelson.topl_core_base.TorSettings.httpTunnelPort]).
+     *
+     * Example of what will be broadcast:
+     *
+     *   - "127.0.0.1:33432"
+     * */
+    abstract fun broadcastHttpPortAddress(httpPortAddress: String?)
+}