A client for the Thread Network API.
Public Method Summary
abstract Task<Void> |
addCredentials(ThreadBorderAgent
borderAgent,
ThreadNetworkCredentials credentials)
Adds the Thread network
credentials to the secure storage.
|
abstract Task<List<ThreadNetworkCredentials>> |
getAllCredentials()
Retrieves all Thread network credentials added by your app.
|
abstract Task<ThreadNetworkCredentialsResult> |
getCredentialsByBorderAgent(ThreadBorderAgent
borderAgent)
Retrieves Thread network credentials with given
borderAgent .
|
abstract Task<IntentSenderResult> |
getCredentialsByExtendedPanId(byte[] extendedPanId)
Retrieves Thread network credentials with given
extendedPanId .
|
abstract Task<IntentSenderResult> |
getPreferredCredentials()
Retrieves the preferred Thread network credentials from the secure storage.
|
abstract Task<Integer> |
isPreferredCredentials(ThreadNetworkCredentials
credentials)
Checks if the
credentials represents the same Thread network as
the preferred network.
|
abstract Task<Void> |
removeCredentials(ThreadBorderAgent
borderAgent)
Removes Thread network credentials of given
borderAgent from the
secure storage.
|
Public Methods
public abstract Task<Void> addCredentials (ThreadBorderAgent borderAgent, ThreadNetworkCredentials credentials)
Adds the Thread network credentials
to the secure storage.
In case there are already Thread network credentials associated with the same
borderAgent
, the credentials will be overwritten if it was added by your
app; otherwise, the returned Task
will fail with a ApiException
with status code
ThreadNetworkStatusCodes.PERMISSION_DENIED
.
public abstract Task<List<ThreadNetworkCredentials>> getAllCredentials ()
Retrieves all Thread network credentials added by your app.
public abstract Task<ThreadNetworkCredentialsResult> getCredentialsByBorderAgent (ThreadBorderAgent borderAgent)
Retrieves Thread network credentials with given borderAgent
.
If the credentials are not added by your app, the returned Task
will
fail with ApiException
with status code
ThreadNetworkStatusCodes.PERMISSION_DENIED
.
public abstract Task<IntentSenderResult> getCredentialsByExtendedPanId (byte[] extendedPanId)
Retrieves Thread network credentials with given extendedPanId
.
For success cases, an IntentSender
will be returned to pop up a consent dialog to ask the user for sharing the credentials
and the credentials will be passed to the caller in ActivityResult
if the user approves. In case there are multiple networks which match
extendedPanId
, the most recently updated network will be returned. If
there are no networks which match extendedPanId
,
IntentSenderResult.getIntentSender()
will return null
.
Unlike
getCredentialsByBorderAgent(ThreadBorderAgent)
, this method can return
Thread network credentials which are added by other apps.
Unlike
getPreferredCredentials()
, this method doesn't require a local network
connection and the returned network may not be the preferred network.
An example of requesting network by Extended PAN ID and retrieving the credentials
from the returned IntentSenderResult
:
// Creates the IntentSender result launcher for the getCredentialsByExtendedPanId API
private ActivityResultLauncher<IntentSenderRequest> getByExtendedPanIdLauncher =
registerForActivityResult(
new StartIntentSenderForResult(),
result -> {
if (result.getResultCode() == RESULT_OK) {
ThreadNetworkCredentials credentials =
ThreadNetworkCredentials.fromIntentSenderResultData(
checkNotNull(result.getData()));
} else {
// The user denied to share!
}
});
// Invokes the getCredentialsByExtendedPanId API and starts the dialog activity with the
// returned IntentSender
threadNetworkClient
.getCredentialsByExtendedPanId(extendedPanId)
.addOnSuccessListener(
intentSenderResult -> {
IntentSender intentSender = intentSenderResult.getIntentSender();
if (intentSender != null) {
getByExtendedPanIdLauncher.launch(
new IntentSenderRequest.Builder(intentSender).build());
} else {
// No network credentials for extendedPanId!
}
})
// Handles the failure
.addOnFailureListener(e -> {});
public abstract Task<IntentSenderResult> getPreferredCredentials ()
Retrieves the preferred Thread network credentials from the secure storage.
Your app must be connected to a local Wi-Fi or Ethernet network. Otherwise, the
returned Task
will fail with ApiException
with status code
ThreadNetworkStatusCodes.LOCAL_NETWORK_NOT_CONNECTED
. For success cases, an
IntentSenderResult
will be returned to pop up a consent dialog to ask the user for sharing the credentials
and the credentials will be passed to the caller in ActivityResult
if the user approves. In case there are no preferred network credentials,
IntentSenderResult.getIntentSender()
will return null
.
Unlike
getCredentialsByBorderAgent(ThreadBorderAgent)
, this method can return
Thread network credentials which are added by other apps.
An example of requesting preferred network and retrieving the credentials from the
returned IntentSenderResult
:
// Creates the IntentSender result launcher for the getPreferredCredentials API
private ActivityResultLauncher<IntentSenderRequest> getPreferredCredentialsLauncher =
registerForActivityResult(
new StartIntentSenderForResult(),
result -> {
if (result.getResultCode() == RESULT_OK) {
ThreadNetworkCredentials preferredCredentials =
ThreadNetworkCredentials.fromIntentSenderResultData(
checkNotNull(result.getData()));
} else {
// The user denied to share!
}
});
// Invokes the getPreferredCredentials API and starts the dialog activity with the returned
// IntentSender
threadNetworkClient
.getPreferredCredentials()
.addOnSuccessListener(
intentSenderResult -> {
IntentSender intentSender = intentSenderResult.getIntentSender();
if (intentSender != null) {
getPreferredCredentialsLauncher.launch(
new IntentSenderRequest.Builder(intentSender).build());
} else {
// No preferred credentials found!
}
})
// Handles the failure
.addOnFailureListener(e -> {});
public abstract Task<Integer> isPreferredCredentials (ThreadNetworkCredentials credentials)
Checks if the credentials
represents the same Thread network as the
preferred network.
Typical usage of this API is to check if an active Thread Border Router is already
in the preferred network before calling
getPreferredCredentials()
which can pop up a consent dialog.
Your app must be connected to a local Wi-Fi or Ethernet network. Otherwise, the
returned Task
will fail with ApiException
with status code
ThreadNetworkStatusCodes.LOCAL_NETWORK_NOT_CONNECTED
.
The return value can be:
public abstract Task<Void> removeCredentials (ThreadBorderAgent borderAgent)
Removes Thread network credentials of given borderAgent
from the secure
storage.
If the Thread network credentials were not added by your app, the returned
Task
will fail with a ApiException
with status code
ThreadNetworkStatusCodes.PERMISSION_DENIED
.