ThreadNetworkClient

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.

Retrieves all Thread network credentials added by your app.

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.

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 -> {});
 

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 -> {});
 

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:

• IsPreferredCredentialsResult.PREFERRED_CREDENTIALS_NOT_FOUND
• IsPreferredCredentialsResult.PREFERRED_CREDENTIALS_NOT_MATCHED
• IsPreferredCredentialsResult.PREFERRED_CREDENTIALS_MATCHED

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.