FileDocCategorySizeDatePackage
WifiManager.javaAPI DocAndroid 1.5 API30717Wed May 06 22:42:04 BST 2009android.net.wifi

WifiManager

public class WifiManager extends Object
This class provides the primary API for managing all aspects of Wi-Fi connectivity. Get an instance of this class by calling {@link android.content.Context#getSystemService(String) Context.getSystemService(Context.WIFI_SERVICE)}. It deals with several categories of items:
  • The list of configured networks. The list can be viewed and updated, and attributes of individual entries can be modified.
  • The currently active Wi-Fi network, if any. Connectivity can be established or torn down, and dynamic information about the state of the network can be queried.
  • Results of access point scans, containing enough information to make decisions about what access point to connect to.
  • It defines the names of various Intent actions that are broadcast upon any sort of change in Wi-Fi state.
This is the API to use when performing Wi-Fi specific operations. To perform operations that pertain to network connectivity at an abstract level, use {@link android.net.ConnectivityManager}.

Fields Summary
public static final int
ERROR_AUTHENTICATING
The error code if there was a problem authenticating.
public static final String
WIFI_STATE_CHANGED_ACTION
Broadcast intent action indicating that Wi-Fi has been enabled, disabled, enabling, disabling, or unknown. One extra provides this state as an int. Another extra provides the previous state, if available.
public static final String
EXTRA_WIFI_STATE
The lookup key for an int that indicates whether Wi-Fi is enabled, disabled, enabling, disabling, or unknown. Retrieve it with {@link android.content.Intent#getIntExtra(String,int)}.
public static final String
EXTRA_PREVIOUS_WIFI_STATE
The previous Wi-Fi state.
public static final int
WIFI_STATE_DISABLING
Wi-Fi is currently being disabled. The state will change to {@link #WIFI_STATE_DISABLED} if it finishes successfully.
public static final int
WIFI_STATE_DISABLED
Wi-Fi is disabled.
public static final int
WIFI_STATE_ENABLING
Wi-Fi is currently being enabled. The state will change to {@link #WIFI_STATE_ENABLED} if it finishes successfully.
public static final int
WIFI_STATE_ENABLED
Wi-Fi is enabled.
public static final int
WIFI_STATE_UNKNOWN
Wi-Fi is in an unknown state. This state will occur when an error happens while enabling or disabling.
public static final String
SUPPLICANT_CONNECTION_CHANGE_ACTION
Broadcast intent action indicating that a connection to the supplicant has been established (and it is now possible to perform Wi-Fi operations) or the connection to the supplicant has been lost. One extra provides the connection state as a boolean, where {@code true} means CONNECTED.
public static final String
EXTRA_SUPPLICANT_CONNECTED
The lookup key for a boolean that indicates whether a connection to the supplicant daemon has been gained or lost. {@code true} means a connection now exists. Retrieve it with {@link android.content.Intent#getBooleanExtra(String,boolean)}.
public static final String
NETWORK_STATE_CHANGED_ACTION
Broadcast intent action indicating that the state of Wi-Fi connectivity has changed. One extra provides the new state in the form of a {@link android.net.NetworkInfo} object. If the new state is CONNECTED, a second extra may provide the BSSID of the access point, as a {@code String}.
public static final String
EXTRA_NETWORK_INFO
The lookup key for a {@link android.net.NetworkInfo} object associated with the Wi-Fi network. Retrieve with {@link android.content.Intent#getParcelableExtra(String)}.
public static final String
EXTRA_BSSID
The lookup key for a String giving the BSSID of the access point to which we are connected. Only present when the new state is CONNECTED. Retrieve with {@link android.content.Intent#getStringExtra(String)}.
public static final String
SUPPLICANT_STATE_CHANGED_ACTION
Broadcast intent action indicating that the state of establishing a connection to an access point has changed.One extra provides the new {@link SupplicantState}. Note that the supplicant state is Wi-Fi specific, and is not generally the most useful thing to look at if you are just interested in the overall state of connectivity.
public static final String
EXTRA_NEW_STATE
The lookup key for a {@link SupplicantState} describing the new state Retrieve with {@link android.content.Intent#getParcelableExtra(String)}.
public static final String
EXTRA_SUPPLICANT_ERROR
The lookup key for a {@link SupplicantState} describing the supplicant error code if any Retrieve with {@link android.content.Intent#getIntExtra(String, int)}.
public static final String
SCAN_RESULTS_AVAILABLE_ACTION
An access point scan has completed, and results are available from the supplicant. Call {@link #getScanResults()} to obtain the results.
public static final String
RSSI_CHANGED_ACTION
The RSSI (signal strength) has changed.
public static final String
EXTRA_NEW_RSSI
The lookup key for an {@code int} giving the new RSSI in dBm.
public static final String
NETWORK_IDS_CHANGED_ACTION
The network IDs of the configured networks could have changed.
public static final String
ACTION_PICK_WIFI_NETWORK
Activity Action: Pick a Wi-Fi network to connect to.

Input: Nothing.

Output: Nothing.

public static final int
WIFI_MODE_FULL
In this Wi-Fi lock mode, Wi-Fi will be kept active, and will behave normally, i.e., it will attempt to automatically establish a connection to a remembered access point that is within range, and will do periodic scans if there are remembered access points but none are in range.
public static final int
WIFI_MODE_SCAN_ONLY
In this Wi-Fi lock mode, Wi-Fi will be kept active, but the only operation that will be supported is initiation of scans, and the subsequent reporting of scan results. No attempts will be made to automatically connect to remembered access points, nor will periodic scans be automatically performed looking for remembered access points. Scans must be explicitly requested by an application in this mode.
private static final int
MIN_RSSI
Anything worse than or equal to this will show 0 bars.
private static final int
MAX_RSSI
Anything better than or equal to this will show the max bars.
IWifiManager
mService
android.os.Handler
mHandler
Constructors Summary
public WifiManager(IWifiManager service, android.os.Handler handler)
Create a new WifiManager instance. Applications will almost always want to use {@link android.content.Context#getSystemService Context.getSystemService()} to retrieve the standard {@link android.content.Context#WIFI_SERVICE Context.WIFI_SERVICE}.

param
service the Binder interface
param
handler target for messages
hide
- hide this because it takes in a parameter of type IWifiManager, which is a system private class.


                                                            
         
        mService = service;
        mHandler = handler;
    
Methods Summary
public intaddNetwork(WifiConfiguration config)
Add a new network description to the set of configured networks. The {@code networkId} field of the supplied configuration object is ignored.

The new network will be marked DISABLED by default. To enable it, called {@link #enableNetwork}.

param
config the set of variables that describe the configuration, contained in a {@link WifiConfiguration} object.
return
the ID of the newly created network description. This is used in other operations to specified the network to be acted upon. Returns {@code -1} on failure.

        if (config == null) {
            return -1;
        }
        config.networkId = -1;
        return addOrUpdateNetwork(config);
    
private intaddOrUpdateNetwork(WifiConfiguration config)
Internal method for doing the RPC that creates a new network description or updates an existing one.

param
config The possibly sparse object containing the variables that are to set or updated in the network description.
return
the ID of the network on success, {@code -1} on failure.

        try {
            return mService.addOrUpdateNetwork(config);
        } catch (RemoteException e) {
            return -1;
        }
    
public static intcalculateSignalLevel(int rssi, int numLevels)
Calculates the level of the signal. This should be used any time a signal is being shown.

param
rssi The power of the signal measured in RSSI.
param
numLevels The number of levels to consider in the calculated level.
return
A level of the signal, given in the range of 0 to numLevels-1 (both inclusive).

        if (rssi <= MIN_RSSI) {
            return 0;
        } else if (rssi >= MAX_RSSI) {
            return numLevels - 1;
        } else {
            int partitionSize = (MAX_RSSI - MIN_RSSI) / (numLevels - 1);
            return (rssi - MIN_RSSI) / partitionSize;
        }
    
public static intcompareSignalLevel(int rssiA, int rssiB)
Compares two signal strengths.

param
rssiA The power of the first signal measured in RSSI.
param
rssiB The power of the second signal measured in RSSI.
return
Returns <0 if the first signal is weaker than the second signal, 0 if the two signals have the same strength, and >0 if the first signal is stronger than the second signal.

        return rssiA - rssiB;
    
public android.net.wifi.WifiManager$WifiLockcreateWifiLock(int lockType, java.lang.String tag)
Creates a new WifiLock.

param
lockType the type of lock to create. See {@link #WIFI_MODE_FULL} and {@link #WIFI_MODE_SCAN_ONLY} for descriptions of the types of Wi-Fi locks.
param
tag a tag for the WifiLock to identify it in debugging messages. This string is never shown to the user under normal conditions, but should be descriptive enough to identify your application and the specific WifiLock within it, if it holds multiple WifiLocks.
return
a new, unacquired WifiLock with the given tag.
see
WifiLock

        return new WifiLock(lockType, tag);
    
public android.net.wifi.WifiManager$WifiLockcreateWifiLock(java.lang.String tag)
Creates a new WifiLock.

param
tag a tag for the WifiLock to identify it in debugging messages. This string is never shown to the user under normal conditions, but should be descriptive enough to identify your application and the specific WifiLock within it, if it holds multiple WifiLocks.
return
a new, unacquired WifiLock with the given tag.
see
WifiLock

        return new WifiLock(WIFI_MODE_FULL, tag);
    
public booleandisableNetwork(int netId)
Disable a configured network. The specified network will not be a candidate for associating. This may result in the asynchronous delivery of state change events.

param
netId the ID of the network as returned by {@link #addNetwork}.
return
{@code true} if the operation succeeded

        try {
            return mService.disableNetwork(netId);
        } catch (RemoteException e) {
            return false;
        }
    
public booleandisconnect()
Disassociate from the currently active access point. This may result in the asynchronous delivery of state change events.

return
{@code true} if the operation succeeded

        try {
            return mService.disconnect();
        } catch (RemoteException e) {
            return false;
        }
    
public booleanenableNetwork(int netId, boolean disableOthers)
Allow a previously configured network to be associated with. If disableOthers is true, then all other configured networks are disabled, and an attempt to connect to the selected network is initiated. This may result in the asynchronous delivery of state change events.

param
netId the ID of the network in the list of configured networks
param
disableOthers if true, disable all other networks. The way to select a particular network to connect to is specify {@code true} for this parameter.
return
{@code true} if the operation succeeded

        try {
            return mService.enableNetwork(netId, disableOthers);
        } catch (RemoteException e) {
            return false;
        }
    
public java.util.ListgetConfiguredNetworks()
Return a list of all the networks configured in the supplicant. Not all fields of WifiConfiguration are returned. Only the following fields are filled in:
  • networkId
  • SSID
  • BSSID
  • priority
  • allowedProtocols
  • allowedKeyManagement
  • allowedAuthAlgorithms
  • allowedPairwiseCiphers
  • allowedGroupCiphers

return
a list of network configurations in the form of a list of {@link WifiConfiguration} objects.

        try {
            return mService.getConfiguredNetworks();
        } catch (RemoteException e) {
            return null;
        }
    
public WifiInfogetConnectionInfo()
Return dynamic information about the current Wi-Fi connection, if any is active.

return
the Wi-Fi information, contained in {@link WifiInfo}.

        try {
            return mService.getConnectionInfo();
        } catch (RemoteException e) {
            return null;
        }
    
public android.net.DhcpInfogetDhcpInfo()
Return the DHCP-assigned addresses from the last successful DHCP request, if any.

return
the DHCP information

        try {
            return mService.getDhcpInfo();
        } catch (RemoteException e) {
            return null;
        }
    
public intgetNumAllowedChannels()
Return the number of frequency channels that are allowed to be used in the current regulatory domain.

return
the number of allowed channels, or {@code -1} if an error occurs
hide
pending API council

        try {
            return mService.getNumAllowedChannels();
        } catch (RemoteException e) {
            return -1;
        }
    
public java.util.ListgetScanResults()
Return the results of the latest access point scan.

return
the list of access points found in the most recent scan.

        try {
            return mService.getScanResults();
        } catch (RemoteException e) {
            return null;
        }
    
public int[]getValidChannelCounts()
Return the list of valid values for the number of allowed radio channels for various regulatory domains.

return
the list of channel counts, or {@code null} if the operation fails
hide
pending API council review

        try {
            return mService.getValidChannelCounts();
        } catch (RemoteException e) {
            return null;
        }
   
public intgetWifiState()
Gets the Wi-Fi enabled state.

return
One of {@link #WIFI_STATE_DISABLED}, {@link #WIFI_STATE_DISABLING}, {@link #WIFI_STATE_ENABLED}, {@link #WIFI_STATE_ENABLING}, {@link #WIFI_STATE_UNKNOWN}
see
#isWifiEnabled()

        try {
            return mService.getWifiEnabledState();
        } catch (RemoteException e) {
            return WIFI_STATE_UNKNOWN;
        }
    
public booleanisWifiEnabled()
Return whether Wi-Fi is enabled or disabled.

return
{@code true} if Wi-Fi is enabled
see
#getWifiState()

        return getWifiState() == WIFI_STATE_ENABLED;
    
public booleanpingSupplicant()
Check that the supplicant daemon is responding to requests.

return
{@code true} if we were able to communicate with the supplicant and it returned the expected response to the PING message.

        if (mService == null)
            return false;
        try {
            return mService.pingSupplicant();
        } catch (RemoteException e) {
            return false;
        }
    
public booleanreassociate()
Reconnect to the currently active access point, even if we are already connected. This may result in the asynchronous delivery of state change events.

return
{@code true} if the operation succeeded

        try {
            return mService.reassociate();
        } catch (RemoteException e) {
            return false;
        }
    
public booleanreconnect()
Reconnect to the currently active access point, if we are currently disconnected. This may result in the asynchronous delivery of state change events.

return
{@code true} if the operation succeeded

        try {
            return mService.reconnect();
        } catch (RemoteException e) {
            return false;
        }
    
public booleanremoveNetwork(int netId)
Remove the specified network from the list of configured networks. This may result in the asynchronous delivery of state change events.

param
netId the integer that identifies the network configuration to the supplicant
return
{@code true} if the operation succeeded

        try {
            return mService.removeNetwork(netId);
        } catch (RemoteException e) {
            return false;
        }
    
public booleansaveConfiguration()
Tell the supplicant to persist the current list of configured networks.

Note: It is possible for this method to change the network IDs of existing networks. You should assume the network IDs can be different after calling this method.

return
{@code true} if the operation succeeded

        try {
            return mService.saveConfiguration();
        } catch (RemoteException e) {
            return false;
        }
    
public booleansetNumAllowedChannels(int numChannels)
Set the number of frequency channels that are allowed to be used in the current regulatory domain. This method should be used only if the correct number of channels cannot be determined automatically for some reason.

param
numChannels the number of allowed channels. Must be greater than 0 and less than or equal to 16.
return
{@code true} if the operation succeeds, {@code false} otherwise, e.g., {@code numChannels} is out of range.
hide
pending API council

        try {
            return mService.setNumAllowedChannels(numChannels);
        } catch (RemoteException e) {
            return false;
        }
    
public booleansetWifiEnabled(boolean enabled)
Enable or disable Wi-Fi.

param
enabled {@code true} to enable, {@code false} to disable.
return
{@code true} if the operation succeeds (or if the existing state is the same as the requested state).

        try {
            return mService.setWifiEnabled(enabled);
        } catch (RemoteException e) {
            return false;
        }
    
public booleanstartScan()
Request a scan for access points. Returns immediately. The availability of the results is made known later by means of an asynchronous event sent on completion of the scan.

return
{@code true} if the operation succeeded, i.e., the scan was initiated

        try {
            return mService.startScan();
        } catch (RemoteException e) {
            return false;
        }
    
public intupdateNetwork(WifiConfiguration config)
Update the network description of an existing configured network.

param
config the set of variables that describe the configuration, contained in a {@link WifiConfiguration} object. It may be sparse, so that only the items that are being changed are non-null. The {@code networkId} field must be set to the ID of the existing network being updated.
return
Returns the {@code networkId} of the supplied {@code WifiConfiguration} on success.
Returns {@code -1} on failure, including when the {@code networkId} field of the {@code WifiConfiguration} does not refer to an existing network.

        if (config == null || config.networkId < 0) {
            return -1;
        }
        return addOrUpdateNetwork(config);