WifiNetworkSpecifier.Builder | API reference

WifiNetworkSpecifier.Builder | API reference | Android Developers

Summary: Ctors | Methods | Inherited Methods

public static final class WifiNetworkSpecifier.Builder
extends Object

Builder used to create WifiNetworkSpecifier objects.

Summary

Public constructors
`Builder()`

Public methods
`WifiNetworkSpecifier`	`build()` Create a specifier object used to request a Wi-Fi network.
`WifiNetworkSpecifier.Builder`	`setBand(int band)` Specifies the band requested for this network.
`WifiNetworkSpecifier.Builder`	`setBssid(MacAddress bssid)` Set the BSSID to use for filtering networks from scan results.
`WifiNetworkSpecifier.Builder`	`setBssidPattern(MacAddress baseAddress, MacAddress mask)` Set the BSSID match pattern to use for filtering networks from scan results.
`WifiNetworkSpecifier.Builder`	`setIsEnhancedOpen(boolean isEnhancedOpen)` Specifies whether this represents an Enhanced Open (OWE) network.
`WifiNetworkSpecifier.Builder`	`setIsHiddenSsid(boolean isHiddenSsid)` Specifies whether this represents a hidden network.
`WifiNetworkSpecifier.Builder`	`setPreferredChannelsFrequenciesMhz(int[] channelFreqs)` Specifies the preferred channels for this network.
`WifiNetworkSpecifier.Builder`	`setSsid(String ssid)` Set the unicode SSID for the network.
`WifiNetworkSpecifier.Builder`	`setSsidPattern(PatternMatcher ssidPattern)` Set the unicode SSID match pattern to use for filtering networks from scan results.
`WifiNetworkSpecifier.Builder`	`setWpa2EnterpriseConfig(WifiEnterpriseConfig enterpriseConfig)` Set the associated enterprise configuration for this network.
`WifiNetworkSpecifier.Builder`	`setWpa2Passphrase(String passphrase)` Set the ASCII WPA2 passphrase for this network.
`WifiNetworkSpecifier.Builder`	`setWpa3Enterprise192BitModeConfig(WifiEnterpriseConfig enterpriseConfig)` Set the associated enterprise configuration for this network.
`WifiNetworkSpecifier.Builder`	`setWpa3EnterpriseConfig(WifiEnterpriseConfig enterpriseConfig)` This method was deprecated in API level 31. use `setWpa3EnterpriseStandardModeConfig(WifiEnterpriseConfig)` or `setWpa3Enterprise192BitModeConfig(WifiEnterpriseConfig)` to specify WPA3-Enterprise type explicitly.
`WifiNetworkSpecifier.Builder`	`setWpa3EnterpriseStandardModeConfig(WifiEnterpriseConfig enterpriseConfig)` Set the associated enterprise configuration for this network.
`WifiNetworkSpecifier.Builder`	`setWpa3Passphrase(String passphrase)` Set the ASCII WPA3 passphrase for this network.

Inherited methods

From class java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeoutMillis, int nanos)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait()` Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public constructors

Builder

public Builder ()

Public methods

build

public WifiNetworkSpecifier build ()

Create a specifier object used to request a Wi-Fi network. The generated NetworkSpecifier should be used in NetworkRequest.Builder.setNetworkSpecifier(NetworkSpecifier) when building the NetworkRequest.

When using with ConnectivityManager.requestNetwork(NetworkRequest,NetworkCallback) or variants, note that some devices may not support requesting a network with all combinations of specifier members. For example, some devices may only support requesting local-only networks (networks without the NetworkCapabilities.NET_CAPABILITY_INTERNET capability), or not support requesting a particular band. However, there are no restrictions when using ConnectivityManager.registerNetworkCallback(NetworkRequest,NetworkCallback) or other similar methods which monitor but do not request networks. If the device can't support a request, the app will receive a call to NetworkCallback.onUnavailable().

When requesting a local-only network, apps can set a combination of network match params:

SSID Pattern using setSsidPattern(PatternMatcher) OR Specific SSID using setSsid(String).

AND/OR

BSSID Pattern using setBssidPattern(MacAddress,MacAddress) OR Specific BSSID using setBssid(MacAddress)

to trigger connection to a network that matches the set params. The system will find the set of networks matching the request and present the user with a system dialog which will allow the user to select a specific Wi-Fi network to connect to or to deny the request. To protect user privacy, some limitations to the ability of matching patterns apply. In particular, when the system brings up a network to satisfy a NetworkRequest from some app, the system reserves the right to decline matching the SSID pattern to the real SSID of the network for other apps than the app that requested the network, and not send those callbacks even if the SSID matches the requested pattern.

For example: To connect to an open network with a SSID prefix of "test" and a BSSID OUI of "10:03:23":

final NetworkSpecifier specifier =
      new Builder()
      .setSsidPattern(new PatternMatcher("test", PatternMatcher.PATTERN_PREFIX))
      .setBssidPattern(MacAddress.fromString("10:03:23:00:00:00"),
                       MacAddress.fromString("ff:ff:ff:00:00:00"))
      .build()
 final NetworkRequest request =
      new NetworkRequest.Builder()
      .addTransportType(NetworkCapabilities.TRANSPORT_WIFI)
      .removeCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
      .setNetworkSpecifier(specifier)
      .build();
 final ConnectivityManager connectivityManager =
      context.getSystemService(Context.CONNECTIVITY_SERVICE);
 final NetworkCallback networkCallback = new NetworkCallback() {
      ...
      {@literal @}Override
      void onAvailable(...) {}
      // etc.
 };
 connectivityManager.requestNetwork(request, networkCallback);

Returns
`WifiNetworkSpecifier`	Instance of `NetworkSpecifier`. This value cannot be `null`.

Throws
`IllegalStateException`	on invalid params set.

setIsEnhancedOpen

public WifiNetworkSpecifier.Builder setIsEnhancedOpen (boolean isEnhancedOpen)

Specifies whether this represents an Enhanced Open (OWE) network.

Parameters
`isEnhancedOpen`	`boolean`: `true` to indicate that the network uses enhanced open, `false` otherwise.

Returns
`WifiNetworkSpecifier.Builder`	Instance of `Builder` to enable chaining of the builder method. This value cannot be `null`.

setIsHiddenSsid

public WifiNetworkSpecifier.Builder setIsHiddenSsid (boolean isHiddenSsid)

Specifies whether this represents a hidden network.

Setting this disallows the usage of setSsidPattern(PatternMatcher) since hidden networks need to be explicitly probed for.

If not set, defaults to false (i.e not a hidden network).

Parameters
`isHiddenSsid`	`boolean`: `true` to indicate that the network is hidden, `false` otherwise.

Returns
`WifiNetworkSpecifier.Builder`	Instance of `Builder` to enable chaining of the builder method. This value cannot be `null`.

setPreferredChannelsFrequenciesMhz

public WifiNetworkSpecifier.Builder setPreferredChannelsFrequenciesMhz (int[] channelFreqs)

Specifies the preferred channels for this network. The channels set in the request will be used to optimize the scan and connection.

Should only be set to request local-only network

If not set, defaults to an empty array and device will do a full band scan.

Parameters
`channelFreqs`	`int`: an Array of the channels in MHz. The length of the array must not exceed `WifiManager.getMaxNumberOfChannelsPerNetworkSpecifierRequest()` This value cannot be `null`.

Returns
`WifiNetworkSpecifier.Builder`	Instance of `Builder` to enable chaining of the builder method. This value cannot be `null`.

setWpa2Passphrase

public WifiNetworkSpecifier.Builder setWpa2Passphrase (String passphrase)

Set the ASCII WPA2 passphrase for this network. Needed for authenticating to WPA2-PSK networks.

Parameters
`passphrase`	`String`: passphrase of the network. This value cannot be `null`.

Returns
`WifiNetworkSpecifier.Builder`	Instance of `Builder` to enable chaining of the builder method. This value cannot be `null`.

Throws
`IllegalArgumentException`	if the passphrase is not ASCII encodable.

setWpa3Enterprise192BitModeConfig

public WifiNetworkSpecifier.Builder setWpa3Enterprise192BitModeConfig (WifiEnterpriseConfig enterpriseConfig)

Set the associated enterprise configuration for this network. Needed for authenticating to WPA3-Enterprise in 192-bit security mode networks. See WifiEnterpriseConfig for description. Both the client and CA certificates must be provided, and must be of type of either sha384WithRSAEncryption with key length of 3072bit or more (OID 1.2.840.113549.1.1.12), or ecdsa-with-SHA384 with key length of 384bit or more (OID 1.2.840.10045.4.3.3). Local-only connection will not support Trust On First Use (TOFU). If TOFU is enabled on this Enterprise Config, framework will reject the connection. See WifiEnterpriseConfig.enableTrustOnFirstUse

Parameters
`enterpriseConfig`	`WifiEnterpriseConfig`: Instance of `WifiEnterpriseConfig`. This value cannot be `null`.

Returns
`WifiNetworkSpecifier.Builder`	Instance of `Builder` to enable chaining of the builder method. This value cannot be `null`.

Throws
`IllegalArgumentException`	if the EAP type or certificates do not meet 192-bit mode requirements.

setWpa3Passphrase

public WifiNetworkSpecifier.Builder setWpa3Passphrase (String passphrase)

Set the ASCII WPA3 passphrase for this network. Needed for authenticating to WPA3-SAE networks.

Parameters
`passphrase`	`String`: passphrase of the network. This value cannot be `null`.

Returns
`WifiNetworkSpecifier.Builder`	Instance of `Builder` to enable chaining of the builder method. This value cannot be `null`.

Throws
`IllegalArgumentException`	if the passphrase is not ASCII encodable.