WifiNetworkSpecifier.Builder
public
static
final
class
WifiNetworkSpecifier.Builder
extends Object
java.lang.Object | |
↳ | android.net.wifi.WifiNetworkSpecifier.Builder |
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 |
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 | |
---|---|
Public constructors
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:
setSsidPattern(android.os.PatternMatcher)
OR Specific SSID using
setSsid(java.lang.String)
. setBssidPattern(android.net.MacAddress, android.net.MacAddress)
OR Specific
BSSID using setBssid(android.net.MacAddress)
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. |
setBand
public WifiNetworkSpecifier.Builder setBand (int band)
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 ScanResult.UNSPECIFIED , ScanResult.WIFI_BAND_24_GHZ , ScanResult.WIFI_BAND_5_GHZ , ScanResult.WIFI_BAND_6_GHZ , or ScanResult.WIFI_BAND_60_GHZ |
Returns | |
---|---|
WifiNetworkSpecifier.Builder |
Instance of Builder to enable chaining of the builder method.
This value cannot be null . |
setBssid
public WifiNetworkSpecifier.Builder setBssid (MacAddress bssid)
Set the BSSID to use for filtering networks from scan results. Will only match network whose BSSID is identical to the specified value.
setBssid(android.net.MacAddress)
or
setBssidPattern(android.net.MacAddress, android.net.MacAddress)
.Parameters | |
---|---|
bssid |
MacAddress : BSSID 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 . |
setBssidPattern
public WifiNetworkSpecifier.Builder setBssidPattern (MacAddress baseAddress, MacAddress mask)
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
.
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 . |
Returns | |
---|---|
WifiNetworkSpecifier.Builder |
Instance of Builder to enable chaining of the builder method.
This value cannot be null . |
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.
setSsidPattern(android.os.PatternMatcher)
since
hidden networks need to be explicitly probed for.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.
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 . |
setSsid
public WifiNetworkSpecifier.Builder setSsid (String ssid)
Set the unicode SSID for the network.
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 . |
Returns | |
---|---|
WifiNetworkSpecifier.Builder |
Instance of Builder to enable chaining of the builder method.
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if the SSID is not valid unicode. |
setSsidPattern
public WifiNetworkSpecifier.Builder setSsidPattern (PatternMatcher ssidPattern)
Set the unicode SSID match pattern to use for filtering networks from scan results.
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 . |
Returns | |
---|---|
WifiNetworkSpecifier.Builder |
Instance of Builder to enable chaining of the builder method.
This value cannot be null . |
setWpa2EnterpriseConfig
public WifiNetworkSpecifier.Builder setWpa2EnterpriseConfig (WifiEnterpriseConfig enterpriseConfig)
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 WifiEnterpriseConfig.enableTrustOnFirstUse(boolean)
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 . |
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. |
setWpa3EnterpriseConfig
public WifiNetworkSpecifier.Builder setWpa3EnterpriseConfig (WifiEnterpriseConfig enterpriseConfig)
This method was deprecated
in API level 31.
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 . |
Returns | |
---|---|
WifiNetworkSpecifier.Builder |
Instance of Builder to enable chaining of the builder method.
This value cannot be null . |
setWpa3EnterpriseStandardModeConfig
public WifiNetworkSpecifier.Builder setWpa3EnterpriseStandardModeConfig (WifiEnterpriseConfig enterpriseConfig)
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 WifiEnterpriseConfig.enableTrustOnFirstUse(boolean)
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 . |
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. |