Added in API level 29

Builder


class Builder
kotlin.Any
   ↳ android.net.wifi.WifiNetworkSpecifier.Builder

Builder used to create WifiNetworkSpecifier objects.

Summary

Public constructors

Public methods
WifiNetworkSpecifier

Create a specifier object used to request a Wi-Fi network.

WifiNetworkSpecifier.Builder
setBand(band: Int)

Specifies the band requested for this network.

WifiNetworkSpecifier.Builder

Set the BSSID to use for filtering networks from scan results.

WifiNetworkSpecifier.Builder
setBssidPattern(baseAddress: MacAddress, mask: MacAddress)

Set the BSSID match pattern to use for filtering networks from scan results.

WifiNetworkSpecifier.Builder
setIsEnhancedOpen(isEnhancedOpen: Boolean)

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

WifiNetworkSpecifier.Builder
setIsHiddenSsid(isHiddenSsid: Boolean)

Specifies whether this represents a hidden network.

WifiNetworkSpecifier.Builder

Specifies the preferred channels for this network.

WifiNetworkSpecifier.Builder
setSsid(ssid: String)

Set the unicode SSID for the network.

WifiNetworkSpecifier.Builder

Set the unicode SSID match pattern to use for filtering networks from scan results.

WifiNetworkSpecifier.Builder

Set the associated enterprise configuration for this network.

WifiNetworkSpecifier.Builder

Set the ASCII WPA2 passphrase for this network.

WifiNetworkSpecifier.Builder

Set the associated enterprise configuration for this network.

WifiNetworkSpecifier.Builder

Set the associated enterprise configuration for this network.

WifiNetworkSpecifier.Builder

Set the associated enterprise configuration for this network.

WifiNetworkSpecifier.Builder

Set the ASCII WPA3 passphrase for this network.

Public constructors

Builder

Added in API level 29
Builder()

Public methods

build

Added in API level 29
fun build(): WifiNetworkSpecifier

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 .

When using with ConnectivityManager#requestNetwork(NetworkRequest, 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(android.os.PatternMatcher) OR Specific SSID using setSsid(java.lang.String).
  • AND/OR
  • BSSID Pattern using setBssidPattern(android.net.MacAddress,android.net.MacAddress) OR Specific BSSID using setBssid(android.net.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":
    <code>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() {
           ...
           { @}Override
           void onAvailable(...) {}
           // etc.
      };
      connectivityManager.requestNetwork(request, networkCallback);
      </code>
    Return
    WifiNetworkSpecifier Instance of NetworkSpecifier. This value cannot be null.
    Exceptions
    java.lang.IllegalStateException on invalid params set.

    setBand

    Added in API level 31
    fun setBand(band: Int): WifiNetworkSpecifier.Builder

    Specifies the band requested for this network. Only a single band can be requested. An app can file multiple callbacks concurrently if they need to know about multiple bands.

    Parameters
    band Int: The requested band. Value is android.net.wifi.ScanResult#UNSPECIFIED, android.net.wifi.ScanResult#WIFI_BAND_24_GHZ, android.net.wifi.ScanResult#WIFI_BAND_5_GHZ, android.net.wifi.ScanResult#WIFI_BAND_6_GHZ, or android.net.wifi.ScanResult#WIFI_BAND_60_GHZ
    Return
    WifiNetworkSpecifier.Builder Instance of Builder to enable chaining of the builder method. This value cannot be null.

    setBssid

    Added in API level 29
    fun setBssid(bssid: MacAddress): WifiNetworkSpecifier.Builder

    Set the BSSID to use for filtering networks from scan results. Will only match network whose BSSID is identical to the specified value.

  • Sets the BSSID to use for filtering networks from scan results. Will only match networks whose BSSID is identical to specified value.
  • Overrides any previous value set using setBssid(android.net.MacAddress) or setBssidPattern(android.net.MacAddress,android.net.MacAddress).
  • Parameters
    bssid MacAddress: BSSID of the network. This value cannot be null.
    Return
    WifiNetworkSpecifier.Builder Instance of Builder to enable chaining of the builder method. This value cannot be null.

    setBssidPattern

    Added in API level 29
    fun setBssidPattern(
        baseAddress: MacAddress,
        mask: MacAddress
    ): WifiNetworkSpecifier.Builder

    Set the BSSID match pattern to use for filtering networks from scan results. Will match all networks with BSSID which satisfies the following: BSSID & mask == baseAddress.

  • Overrides any previous value set using setBssid(android.net.MacAddress) or setBssidPattern(android.net.MacAddress,android.net.MacAddress).
  • Parameters
    baseAddress MacAddress: Base address for BSSID pattern. This value cannot be null.
    mask MacAddress: Mask for BSSID pattern. This value cannot be null.
    Return
    WifiNetworkSpecifier.Builder Instance of Builder to enable chaining of the builder method. This value cannot be null.

    setIsEnhancedOpen

    Added in API level 29
    fun setIsEnhancedOpen(isEnhancedOpen: Boolean): WifiNetworkSpecifier.Builder

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

    Parameters
    isEnhancedOpen Boolean: true to indicate that the network uses enhanced open, false otherwise.
    Return
    WifiNetworkSpecifier.Builder Instance of Builder to enable chaining of the builder method. This value cannot be null.

    setIsHiddenSsid

    Added in API level 29
    fun setIsHiddenSsid(isHiddenSsid: Boolean): WifiNetworkSpecifier.Builder

    Specifies whether this represents a hidden network.

  • Setting this disallows the usage of setSsidPattern(android.os.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.
    Return
    WifiNetworkSpecifier.Builder Instance of Builder to enable chaining of the builder method. This value cannot be null.

    setPreferredChannelsFrequenciesMhz

    Added in API level 34
    fun setPreferredChannelsFrequenciesMhz(channelFreqs: IntArray): WifiNetworkSpecifier.Builder

    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 IntArray: an Array of the channels in MHz. The length of the array must not exceed WifiManager#getMaxNumberOfChannelsPerNetworkSpecifierRequest() This value cannot be null.
    Return
    WifiNetworkSpecifier.Builder Instance of Builder to enable chaining of the builder method. This value cannot be null.

    setSsid

    Added in API level 29
    fun setSsid(ssid: String): WifiNetworkSpecifier.Builder

    Set the unicode SSID for the network.

  • Sets the SSID to use for filtering networks from scan results. Will only match networks whose SSID is identical to the UTF-8 encoding of the specified value.
  • Overrides any previous value set using setSsid(java.lang.String) or setSsidPattern(android.os.PatternMatcher).
  • Parameters
    ssid String: The SSID of the network. It must be valid Unicode. This value cannot be null.
    Return
    WifiNetworkSpecifier.Builder Instance of Builder to enable chaining of the builder method. This value cannot be null.
    Exceptions
    java.lang.IllegalArgumentException if the SSID is not valid unicode.

    setSsidPattern

    Added in API level 29
    fun setSsidPattern(ssidPattern: PatternMatcher): WifiNetworkSpecifier.Builder

    Set the unicode SSID match pattern to use for filtering networks from scan results.

  • Overrides any previous value set using setSsid(java.lang.String) or setSsidPattern(android.os.PatternMatcher).
  • Parameters
    ssidPattern PatternMatcher: Instance of PatternMatcher containing the UTF-8 encoded string pattern to use for matching the network's SSID. This value cannot be null.
    Return
    WifiNetworkSpecifier.Builder Instance of Builder to enable chaining of the builder method. This value cannot be null.

    setWpa2EnterpriseConfig

    Added in API level 29
    fun setWpa2EnterpriseConfig(enterpriseConfig: WifiEnterpriseConfig): WifiNetworkSpecifier.Builder

    Set the associated enterprise configuration for this network. Needed for authenticating to WPA2-EAP networks. See WifiEnterpriseConfig for description. 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 android.net.wifi.WifiEnterpriseConfig#enableTrustOnFirstUse

    Parameters
    enterpriseConfig WifiEnterpriseConfig: Instance of WifiEnterpriseConfig. This value cannot be null.
    Return
    WifiNetworkSpecifier.Builder Instance of Builder to enable chaining of the builder method. This value cannot be null.

    setWpa2Passphrase

    Added in API level 29
    fun setWpa2Passphrase(passphrase: String): WifiNetworkSpecifier.Builder

    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.
    Return
    WifiNetworkSpecifier.Builder Instance of Builder to enable chaining of the builder method. This value cannot be null.
    Exceptions
    java.lang.IllegalArgumentException if the passphrase is not ASCII encodable.

    setWpa3Enterprise192BitModeConfig

    Added in API level 31
    fun setWpa3Enterprise192BitModeConfig(enterpriseConfig: WifiEnterpriseConfig): WifiNetworkSpecifier.Builder

    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.
    Return
    WifiNetworkSpecifier.Builder Instance of Builder to enable chaining of the builder method. This value cannot be null.
    Exceptions
    java.lang.IllegalArgumentException if the EAP type or certificates do not meet 192-bit mode requirements.

    setWpa3EnterpriseConfig

    Added in API level 29
    Deprecated in API level 31
    fun setWpa3EnterpriseConfig(enterpriseConfig: WifiEnterpriseConfig): WifiNetworkSpecifier.Builder

    Deprecated: use setWpa3EnterpriseStandardModeConfig(android.net.wifi.WifiEnterpriseConfig) or setWpa3Enterprise192BitModeConfig(android.net.wifi.WifiEnterpriseConfig) to specify WPA3-Enterprise type explicitly.

    Set the associated enterprise configuration for this network. Needed for authenticating to WPA3-Enterprise networks (standard and 192-bit security). See WifiEnterpriseConfig for description. For 192-bit security networks, both the client and CA certificates must be provided, and must be of type of either sha384WithRSAEncryption (OID 1.2.840.113549.1.1.12) or ecdsa-with-SHA384 (OID 1.2.840.10045.4.3.3).

    Parameters
    enterpriseConfig WifiEnterpriseConfig: Instance of WifiEnterpriseConfig. This value cannot be null.
    Return
    WifiNetworkSpecifier.Builder Instance of Builder to enable chaining of the builder method. This value cannot be null.

    setWpa3EnterpriseStandardModeConfig

    Added in API level 31
    fun setWpa3EnterpriseStandardModeConfig(enterpriseConfig: WifiEnterpriseConfig): WifiNetworkSpecifier.Builder

    Set the associated enterprise configuration for this network. Needed for authenticating to standard WPA3-Enterprise networks. See WifiEnterpriseConfig for description. For WPA3-Enterprise in 192-bit security mode networks, see setWpa3Enterprise192BitModeConfig(android.net.wifi.WifiEnterpriseConfig) for description. 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 android.net.wifi.WifiEnterpriseConfig#enableTrustOnFirstUse

    Parameters
    enterpriseConfig WifiEnterpriseConfig: Instance of WifiEnterpriseConfig. This value cannot be null.
    Return
    WifiNetworkSpecifier.Builder Instance of Builder to enable chaining of the builder method. This value cannot be null.

    setWpa3Passphrase

    Added in API level 29
    fun setWpa3Passphrase(passphrase: String): WifiNetworkSpecifier.Builder

    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.
    Return
    WifiNetworkSpecifier.Builder Instance of Builder to enable chaining of the builder method. This value cannot be null.
    Exceptions
    java.lang.IllegalArgumentException if the passphrase is not ASCII encodable.