Merge pull request #101 from zelloptt/tasks/ANDROID-1458-foreground-s…

…ervice-failure-cases ANDROID-1458 Add error callbacks when Zello foreground service fails to start
zelloptt · Jul 26, 2024 · 6fe444e · 6fe444e
2 parents c7e8885 + 52763d4
commit 6fe444e
Show file tree

Hide file tree

Showing 48 changed files with 177 additions and 57 deletions.
diff --git a/docs/zello-sdk-documentation/allclasses-index.html b/docs/zello-sdk-documentation/allclasses-index.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="script.js"></script>
-<script type="text/javascript" src="script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="all-classes-index-page">

diff --git a/docs/zello-sdk-documentation/allpackages-index.html b/docs/zello-sdk-documentation/allpackages-index.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="script.js"></script>
-<script type="text/javascript" src="script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="all-packages-index-page">

diff --git a/docs/zello-sdk-documentation/com/zello/sdk/AppState.html b/docs/zello-sdk-documentation/com/zello/sdk/AppState.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="../../../script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
-<script type="text/javascript" src="../../../script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="../../../script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="../../../script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="class-declaration-page">

diff --git a/docs/zello-sdk-documentation/com/zello/sdk/Audio.html b/docs/zello-sdk-documentation/com/zello/sdk/Audio.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="../../../script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
-<script type="text/javascript" src="../../../script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="../../../script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="../../../script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="class-declaration-page">

diff --git a/docs/zello-sdk-documentation/com/zello/sdk/AudioMode.html b/docs/zello-sdk-documentation/com/zello/sdk/AudioMode.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="../../../script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
-<script type="text/javascript" src="../../../script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="../../../script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="../../../script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="class-declaration-page">

diff --git a/docs/zello-sdk-documentation/com/zello/sdk/BluetoothAccessoryState.html b/docs/zello-sdk-documentation/com/zello/sdk/BluetoothAccessoryState.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="../../../script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
-<script type="text/javascript" src="../../../script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="../../../script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="../../../script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="class-declaration-page">

diff --git a/docs/zello-sdk-documentation/com/zello/sdk/BluetoothAccessoryType.html b/docs/zello-sdk-documentation/com/zello/sdk/BluetoothAccessoryType.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="../../../script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
-<script type="text/javascript" src="../../../script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="../../../script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="../../../script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="class-declaration-page">

diff --git a/docs/zello-sdk-documentation/com/zello/sdk/Contact.html b/docs/zello-sdk-documentation/com/zello/sdk/Contact.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="../../../script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
-<script type="text/javascript" src="../../../script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="../../../script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="../../../script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="class-declaration-page">

diff --git a/docs/zello-sdk-documentation/com/zello/sdk/ContactStatus.html b/docs/zello-sdk-documentation/com/zello/sdk/ContactStatus.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="../../../script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
-<script type="text/javascript" src="../../../script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="../../../script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="../../../script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="class-declaration-page">

diff --git a/docs/zello-sdk-documentation/com/zello/sdk/ContactType.html b/docs/zello-sdk-documentation/com/zello/sdk/ContactType.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="../../../script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
-<script type="text/javascript" src="../../../script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="../../../script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="../../../script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="class-declaration-page">

diff --git a/docs/zello-sdk-documentation/com/zello/sdk/Contacts.html b/docs/zello-sdk-documentation/com/zello/sdk/Contacts.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="../../../script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
-<script type="text/javascript" src="../../../script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="../../../script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="../../../script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="class-declaration-page">

diff --git a/docs/zello-sdk-documentation/com/zello/sdk/Error.html b/docs/zello-sdk-documentation/com/zello/sdk/Error.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="../../../script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
-<script type="text/javascript" src="../../../script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="../../../script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="../../../script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="class-declaration-page">

diff --git a/docs/zello-sdk-documentation/com/zello/sdk/Events.html b/docs/zello-sdk-documentation/com/zello/sdk/Events.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="../../../script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
-<script type="text/javascript" src="../../../script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="../../../script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="../../../script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="class-declaration-page">
@@ -115,26 +115,32 @@ <h2>Method Summary</h2>
  Called when the <a href="Contacts.html" title="class in com.zello.sdk"><code>Contacts</code></a> for the user changes.</div>
 </div>
 <div class="col-first even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code>void</code></div>
-<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#onLastContactsTabChanged(com.zello.sdk.Tab)" class="member-name-link">onLastContactsTabChanged</a><wbr>(<a href="Tab.html" title="enum class in com.zello.sdk">Tab</a>&nbsp;tab)</code></div>
+<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#onForegroundServiceStartFailed(java.lang.Throwable)" class="member-name-link">onForegroundServiceStartFailed</a><wbr>(<a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Throwable.html" title="class or interface in java.lang" class="external-link">Throwable</a>&nbsp;t)</code></div>
 <div class="col-last even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
 <div class="block">
- Called when the last <a href="Contacts.html" title="class in com.zello.sdk"><code>Contacts</code></a> <a href="Tab.html" title="enum class in com.zello.sdk"><code>Tab</code></a> changes.</div>
+ Called when an attempt to start the Zello foreground service fails.</div>
 </div>
 <div class="col-first odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code>void</code></div>
-<div class="col-second odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#onMessageStateChanged()" class="member-name-link">onMessageStateChanged</a>()</code></div>
+<div class="col-second odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#onLastContactsTabChanged(com.zello.sdk.Tab)" class="member-name-link">onLastContactsTabChanged</a><wbr>(<a href="Tab.html" title="enum class in com.zello.sdk">Tab</a>&nbsp;tab)</code></div>
 <div class="col-last odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
 <div class="block">
- Called when the state of either the <a href="MessageOut.html" title="class in com.zello.sdk"><code>MessageOut</code></a> or <a href="MessageIn.html" title="class in com.zello.sdk"><code>MessageIn</code></a> changes.</div>
+ Called when the last <a href="Contacts.html" title="class in com.zello.sdk"><code>Contacts</code></a> <a href="Tab.html" title="enum class in com.zello.sdk"><code>Tab</code></a> changes.</div>
 </div>
 <div class="col-first even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code>void</code></div>
-<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#onMicrophonePermissionNotGranted()" class="member-name-link">onMicrophonePermissionNotGranted</a>()</code></div>
+<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#onMessageStateChanged()" class="member-name-link">onMessageStateChanged</a>()</code></div>
 <div class="col-last even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
 <div class="block">
- Called when an invocation of the <a href="Zello.html#beginMessage()"><code>Zello.beginMessage()</code></a> method fails because the microphone permission hasn't been granted.</div>
+ Called when the state of either the <a href="MessageOut.html" title="class in com.zello.sdk"><code>MessageOut</code></a> or <a href="MessageIn.html" title="class in com.zello.sdk"><code>MessageIn</code></a> changes.</div>
 </div>
 <div class="col-first odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code>void</code></div>
-<div class="col-second odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#onSelectedContactChanged()" class="member-name-link">onSelectedContactChanged</a>()</code></div>
+<div class="col-second odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#onMicrophonePermissionNotGranted()" class="member-name-link">onMicrophonePermissionNotGranted</a>()</code></div>
 <div class="col-last odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
+<div class="block">
+ Called when an invocation of the <a href="Zello.html#beginMessage()"><code>Zello.beginMessage()</code></a> method fails because the microphone permission hasn't been granted.</div>
+</div>
+<div class="col-first even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code>void</code></div>
+<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#onSelectedContactChanged()" class="member-name-link">onSelectedContactChanged</a>()</code></div>
+<div class="col-last even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
 <div class="block">
  Called when the selected contact changes.</div>
 </div>
@@ -351,6 +357,35 @@ <h3>onBluetoothAccessoryStateChanged</h3>
 </dl>
 </section>
 </li>
+<li>
+<section class="detail" id="onForegroundServiceStartFailed(java.lang.Throwable)">
+<h3>onForegroundServiceStartFailed</h3>
+<div class="member-signature"><span class="return-type">void</span>&nbsp;<span class="element-name">onForegroundServiceStartFailed</span><wbr><span class="parameters">(@Nullable
+ <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Throwable.html" title="class or interface in java.lang" class="external-link">Throwable</a>&nbsp;t)</span></div>
+<div class="block"><p>
+ Called when an attempt to start the Zello foreground service fails.
+ </p>
+ <p>
+ This method is invoked on the UI thread.
+ </p>
+ <p>
+ It is the responsibility of the app using the SDK to determine if and how to handle this error.
+ The most likely cause is that the app connecting to Zello was not displaying any UI at the
+ time when the foreground service was started. In this case, the implementing app may call
+ <a href="Zello.html#unconfigure()"><code>Zello.unconfigure()</code></a> followed by <a href="Zello.html#configure(android.content.Context)"><code>Zello.configure(Context)</code></a>
+ (or one of its overloads) once its UI is in the foreground to attempt to start the foreground
+ service again.
+ </p>
+ <p>
+ In Android 14 and above, requirements for foreground services have become stricter. For
+ the most up-to-date information, please refer to the Android documentation.
+ </p></div>
+<dl class="notes">
+<dt>Parameters:</dt>
+<dd><code>t</code> - The exception that caused the failure if available.</dd>
+</dl>
+</section>
+</li>
 </ul>
 </section>
 </li>

diff --git a/docs/zello-sdk-documentation/com/zello/sdk/MessageIn.html b/docs/zello-sdk-documentation/com/zello/sdk/MessageIn.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="../../../script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
-<script type="text/javascript" src="../../../script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="../../../script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="../../../script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="class-declaration-page">

diff --git a/docs/zello-sdk-documentation/com/zello/sdk/MessageOut.html b/docs/zello-sdk-documentation/com/zello/sdk/MessageOut.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="../../../script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
-<script type="text/javascript" src="../../../script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="../../../script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="../../../script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="class-declaration-page">

diff --git a/docs/zello-sdk-documentation/com/zello/sdk/PermissionError.html b/docs/zello-sdk-documentation/com/zello/sdk/PermissionError.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="../../../script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
-<script type="text/javascript" src="../../../script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="../../../script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="../../../script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="class-declaration-page">
@@ -103,17 +103,21 @@ <h2>Enum Constant Summary</h2>
 <div class="summary-table two-column-summary">
 <div class="table-header col-first">Enum Constant</div>
 <div class="table-header col-last">Description</div>
-<div class="col-first even-row-color"><code><a href="#MICROPHONE_NOT_GRANTED" class="member-name-link">MICROPHONE_NOT_GRANTED</a></code></div>
+<div class="col-first even-row-color"><code><a href="#FOREGROUND_SERVICE_NOT_ALLOWED" class="member-name-link">FOREGROUND_SERVICE_NOT_ALLOWED</a></code></div>
 <div class="col-last even-row-color">
-<div class="block">Microphone permission error.</div>
+<div class="block">Foreground service cannot start.</div>
 </div>
-<div class="col-first odd-row-color"><code><a href="#NONE" class="member-name-link">NONE</a></code></div>
+<div class="col-first odd-row-color"><code><a href="#MICROPHONE_NOT_GRANTED" class="member-name-link">MICROPHONE_NOT_GRANTED</a></code></div>
 <div class="col-last odd-row-color">
-<div class="block">No error.</div>
+<div class="block">Microphone permission error.</div>
 </div>
-<div class="col-first even-row-color"><code><a href="#UNKNOWN" class="member-name-link">UNKNOWN</a></code></div>
+<div class="col-first even-row-color"><code><a href="#NONE" class="member-name-link">NONE</a></code></div>
 <div class="col-last even-row-color">
-<div class="block">Unknown perimssion error.</div>
+<div class="block">No error.</div>
+</div>
+<div class="col-first odd-row-color"><code><a href="#UNKNOWN" class="member-name-link">UNKNOWN</a></code></div>
+<div class="col-last odd-row-color">
+<div class="block">Unknown permission error.</div>
 </div>
 </div>
 </section>
@@ -171,7 +175,7 @@ <h3>NONE</h3>
 <section class="detail" id="UNKNOWN">
 <h3>UNKNOWN</h3>
 <div class="member-signature"><span class="modifiers">public static final</span>&nbsp;<span class="return-type"><a href="PermissionError.html" title="enum class in com.zello.sdk">PermissionError</a></span>&nbsp;<span class="element-name">UNKNOWN</span></div>
-<div class="block">Unknown perimssion error.</div>
+<div class="block">Unknown permission error.</div>
 </section>
 </li>
 <li>
@@ -181,6 +185,13 @@ <h3>MICROPHONE_NOT_GRANTED</h3>
 <div class="block">Microphone permission error.</div>
 </section>
 </li>
+<li>
+<section class="detail" id="FOREGROUND_SERVICE_NOT_ALLOWED">
+<h3>FOREGROUND_SERVICE_NOT_ALLOWED</h3>
+<div class="member-signature"><span class="modifiers">public static final</span>&nbsp;<span class="return-type"><a href="PermissionError.html" title="enum class in com.zello.sdk">PermissionError</a></span>&nbsp;<span class="element-name">FOREGROUND_SERVICE_NOT_ALLOWED</span></div>
+<div class="block">Foreground service cannot start.</div>
+</section>
+</li>
 </ul>
 </section>
 </li>

diff --git a/docs/zello-sdk-documentation/com/zello/sdk/SafeHandler.html b/docs/zello-sdk-documentation/com/zello/sdk/SafeHandler.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="../../../script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
-<script type="text/javascript" src="../../../script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="../../../script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="../../../script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="class-declaration-page">

diff --git a/docs/zello-sdk-documentation/com/zello/sdk/SafeHandlerEvents.html b/docs/zello-sdk-documentation/com/zello/sdk/SafeHandlerEvents.html
@@ -11,7 +11,7 @@
 <link rel="stylesheet" type="text/css" href="../../../script-dir/jquery-ui.min.css" title="Style">
 <link rel="stylesheet" type="text/css" href="../../../jquery-ui.overrides.css" title="Style">
 <script type="text/javascript" src="../../../script.js"></script>
-<script type="text/javascript" src="../../../script-dir/jquery-3.6.0.min.js"></script>
+<script type="text/javascript" src="../../../script-dir/jquery-3.6.1.min.js"></script>
 <script type="text/javascript" src="../../../script-dir/jquery-ui.min.js"></script>
 </head>
 <body class="class-declaration-page">