ThreadNetworkClient

public interface ThreadNetworkClient implements HasApiKey<Api.ApiOptions.NoOptions>

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<IntentSenderResult>	getAllActiveCredentials(GetAllActiveCredentialsRequest request) Retrieves the credentials of all known active networks in the current network.
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<IntentSenderResult> getAllActiveCredentials (GetAllActiveCredentialsRequest request)

Retrieves the credentials of all known active networks in the current network.

Typical usage of this API is to choose a network to setup another Thread device, as the preferred network might not always be available.

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.

An example of requesting active known networks and retrieve the credentials from the returned IntentSenderResult:

 // Creates the IntentSender result launcher for the getAllActiveCredentials API
 private ActivityResultLauncher<IntentSenderRequest> getAllActiveCredentialsLauncher =
     registerForActivityResult(
         new StartIntentSenderForResult(),
         result -> {
           if (result.getResultCode() == RESULT_OK) {
             List<ThreadNetworkCredentials> activeCredentials =
                 ThreadNetworkCredentials.parseListFromIntentSenderResultData(
                     checkNotNull(result.getData()));
           } else {
             // The user denied to share!
           }
         });

 // Invokes the getAllActiveCredentials API and starts the dialog activity with the returned
 // IntentSender
 threadNetworkClient
     .getAllActiveCredentials()
     .addOnSuccessListener(
         intentSenderResult -> {
           IntentSender intentSender = intentSenderResult.getIntentSender();
           if (intentSender != null) {
             getAllActiveCredentialsLauncher.launch(
                 new IntentSenderRequest.Builder(intentSender).build());
           } else {
             // No preferred credentials found!
           }
         })
     // Handles the failure
     .addOnFailureListener(e -> {});

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.