The local Bluetooth device is controlled via the BluetoothAdapter class.

To access the default Bluetooth adapter on the host device call getDefaultAdapter, as shown in Listing 13-1. It is possible that some Android devices will feature multiple Bluetooth adapters, though it is currently only possible to access the default device.

BluetoothAdapter bluetooth = BluetoothAdapter.getDefaultAdapter();

To read any of the local Bluetooth Adapter properties, initiate discovery, or find bonded devices you will need to include the BLUETOOTH manifest permission. In order to modify any of the local device properties the BLUETOOTH_ADMIN uses-permission is also required.

<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>

The Bluetooth Adapter offers methods for reading and setting properties of the local Bluetooth hardware.

If the Bluetooth Adapter is turned on, and you have included the BLUETOOTH permission in your manifest, you can access the Bluetooth Adapter's friendly name (an arbitrary string that users can set and then use to identify a particular device) and hardware address, as shown in Listing 13-2.

Use the isEnabled method, as shown in Listing 13-2, to confirm the device is enabled before accessing these properties.

BluetoothAdapter bluetooth = BluetoothAdapter.getDefaultAdapter();

String toastText;
if (bluetooth.isEnabled()) {
  String address = bluetooth.getAddress();
  String name = bluetooth.getName();
  toastText = name + " : " + address;
}
else
  toastText = "Bluetooth is not enabled";

Toast.makeText(this, toastText, Toast.LENGTH_LONG).show();

If you also have the BLUETOOTH_ADMIN permission you can change the friendly name of the Bluetooth Adapter using the setName method:

bluetooth.setName("Blackfang");

To find a more detailed description of the current Bluetooth Adapter state, use the getState method, which will return one of the following BluetoothAdapter constants:

By default the Bluetooth adapter will be turned off. In order to conserve battery life and optimize security, most users will keep Bluetooth disabled unless it's in use.

To enable the Bluetooth Adapter you can start a system sub-Activity using the ACTION_REQUEST_ENABLE Bluetooth Adapter static constant as a startActivityForResult action string:

String enableBT = BluetoothAdapter.ACTION_REQUEST_ENABLE;
startActivityForResult(new Intent(enableBT), 0);

The sub-Activity is shown in Figure 13-1. It prompts the user to turn on Bluetooth and asks for confirmation. If the user agrees, the sub-Activity will close and return to the calling Activity once the Bluetooth Adapter has turned on (or has encountered an error). If the user selects no, the sub-Activity will close and return immediately. Use the result code parameter returned in the onActivityResult handler to determine the success of this operation.

Figure 13-1. FIGURE 13-1

Enabling and disabling the Bluetooth Adapter are somewhat time-consuming, asynchronous operations. Rather than polling the Bluetooth Adapter, your application should register a Broadcast Receiver that listens for ACTION_STATE_CHANGED. The broadcast Intent will include two extras, EXTRA_STATE and EXTRA_PREVIOUS_STATE, which indicate the current and previous Bluetooth Adapter states, respectively.

Listing 13-3 shows how to use an Intent to prompt the user to enable Bluetooth and a Broadcast Receiver to track changes in the Bluetooth Adapter status.

BluetoothAdapter bluetooth = BluetoothAdapter.getDefaultAdapter();

BroadcastReceiver bluetoothState = new BroadcastReceiver() {
  @Override
  public void onReceive(Context context, Intent intent) {
    String prevStateExtra = BluetoothAdapter.EXTRA_PREVIOUS_STATE;
    String stateExtra = BluetoothAdapter.EXTRA_STATE;
    int state = intent.getIntExtra(stateExtra, −1);
    int previousState = intent.getIntExtra(prevStateExtra, −1);

    String tt = "";
    switch (state) {
      case (BluetoothAdapter.STATE_TURNING_ON) : {
        tt = "Bluetooth turning on"; break;
      }
      case (BluetoothAdapter.STATE_ON) : {
        tt = "Bluetooth on";
        unregisterReceiver(this);
        break;
      }
      case (BluetoothAdapter.STATE_TURNING_OFF) : {
        tt = "Bluetooth turning off"; break;
      }
      case (BluetoothAdapter.STATE_OFF) : {
        tt = "Bluetooth off"; break;
      }
      default: break;
    }

    Toast.makeText(this, tt, Toast.LENGTH_LONG).show();
  }
};

if (!bluetooth.isEnabled()) {
  String actionStateChanged = BluetoothAdapter.ACTION_STATE_CHANGED;
  String actionRequestEnable = BluetoothAdapter.ACTION_REQUEST_ENABLE;
  registerReceiver(bluetoothState,
                   new IntentFilter(actionStateChanged));
  startActivityForResult(new Intent(actionRequestEnable), 0);
}

The process of two devices finding each other in order to connect is called discovery. Before you can establish a Bluetooth Socket for communications, the local Bluetooth Adapter must bond with the remote device. Before two devices can bond and connect, they first need to discover each other.

Managing Device Discoverability

In order for remote Android Devices to find your local Bluetooth Adapter during a discovery scan, you need to ensure that it is discoverable.

The Bluetooth Adapter's discoverability is indicated by its scan mode. You can find the adapter's scan mode by calling getScanMode on the BluetoothAdapter object. It will return one of the following BluetoothAdapter constants:

• SCAN_MODE_CONNECTABLE_DISCOVERABLE Inquiry scan and page scan are both enabled, meaning that the device is discoverable from any Bluetooth device performing a discovery scan.

• SCAN_MODE_CONNECTABLE Page Scan is enabled but inquiry scan is not. This means that devices that have previously connected and bonded to the local device can find it during discovery, but new devices can't.

• SCAN_MODE_NONE Discoverability is turned off. No remote devices can find the local adapter during discovery.

Figure 13-2. FIGURE 13-2

For privacy reasons, Android devices will default to having discoverability disabled. To turn on discovery you need to obtain explicit permission from the user; you do this by starting a new Activity using the ACTION_REQUEST_DISCOVERABLE action:

String aDiscoverable = BluetoothAdapter.ACTION_REQUEST_DISCOVERABLE;
startActivityForResult(new Intent(aDiscoverable),
                       DISCOVERY_REQUEST);

By default discoverability will be enabled for two minutes. You can modify this setting by adding an EXTRA_DISCOVERABLE_DURATION extra to the launch Intent, specifying the number of seconds you want discoverability to last.

When the Intent is broadcast the user will be prompted by the dialog shown in Figure 13-2 to turn discoverability on for the specified duration.

To learn if the user has allowed or rejected your discovery request, override the onActivityResult handler, as shown in Listing 13-4. The returned resultCode parameter indicates the duration of discoverability, or a negative number if the user has rejected your request.

Example 13-4. Monitoring discoverability modes

@Override
protected void onActivityResult(int requestCode,
                                int resultCode, Intent data) {
  if (requestCode == DISCOVERY_REQUEST) {
    boolean isDiscoverable = resultCode > 0;
    int discoverableDuration = resultCode;
  }
}

Alternatively you can monitor changes in discoverability by receiving the ACTION_SCAN_MODE_CHANGED broadcast action, as shown in Listing 13-5. The broadcast Intent includes the current and previous scan modes as extras.

Example 13-5. Monitoring discoverability modes

registerReceiver(new BroadcastReceiver() {
  @Override
  public void onReceive(Context context, Intent intent) {
    String prevScanMode = BluetoothAdapter.EXTRA_PREVIOUS_SCAN_MODE;
    String scanMode = BluetoothAdapter.EXTRA_SCAN_MODE;
    int scanMode = intent.getIntExtra(scanMode, −1);

    int prevMode = intent.getIntExtra(prevScanMode, −1);
  }
},
new IntentFilter(BluetoothAdapter.ACTION_SCAN_MODE_CHANGED));

bluetooth.startDiscovery();
bluetooth.cancelDiscovery();

BroadcastReceiver discoveryMonitor = new BroadcastReceiver() {

  String dStarted = BluetoothAdapter.ACTION_DISCOVERY_STARTED;
  String dFinished = BluetoothAdapter.ACTION_DISCOVERY_FINISHED;

  @Override
  public void onReceive(Context context, Intent intent) {
    if (dStarted.equals(intent.getAction())) {
      // Discovery has started.
      Toast.makeText(getApplicationContext(),
                     "Discovery Started...", Toast.LENGTH_SHORT).show();
    }
    else if (dFinished.equals(intent.getAction())) {
      // Discovery has completed.
      Toast.makeText(getApplicationContext(),
                     "Discovery Completed...", Toast.LENGTH_SHORT).show();
    }
  }
};
registerReceiver(discoveryMonitor,
                 new IntentFilter(dStarted));
registerReceiver(discoveryMonitor,
                 new IntentFilter(dFinished));

BroadcastReceiver discoveryResult = new BroadcastReceiver() {
  @Override
  public void onReceive(Context context, Intent intent) {
    String remoteDeviceName =
      intent.getStringExtra(BluetoothDevice.EXTRA_NAME);

BluetoothDevice remoteDevice;
    remoteDevice = intent.getParcelableExtra(BluetoothDevice.EXTRA_DEVICE);

    Toast.makeText(getApplicationContext(),
                   "Discovered: " + remoteDeviceName,
                   Toast.LENGTH_SHORT).show();

    // TODO Do something with the remote Bluetooth Device.
  }
};
registerReceiver(discoveryResult,
                 new IntentFilter(BluetoothDevice.ACTION_FOUND));

if (!bluetooth.isDiscovering())
  bluetooth.startDiscovery();

The Bluetooth communications APIs are wrappers around RFCOMM, the Bluetooth radio frequency communications protocol. RFCOMM supports RS232 serial communication over the Logical Link Control and Adaptation Protocol (L2CAP) layer.

In practice, this alphabet soup provides a mechanism for opening communication sockets between two paired Bluetooth devices.

You can establish an RFCOMM communication channel for bidirectional communications using the following classes.

When creating an application that uses Bluetooth as a peer-to-peer transport layer, you'll need to implement both a Bluetooth Server Socket to listen for connections and a Bluetooth Socket to initiate a new channel and handle communications.

Once connected, the Socket Server returns a Bluetooth Socket that's subsequently used by the server device to send and receive data. This server-side Bluetooth Socket is used in exactly the same way as the client socket. The designations of server and client are relevant only to how the connection is established. They don't affect how data flows once that connection is made.

Opening a Bluetooth Server Socket Listener

A Bluetooth Server Socket is used to listen for incoming Bluetooth Socket connection requests from remote Bluetooth Devices. In order for two Bluetooth devices to be connected, one must act as a server (listening for and accepting incoming requests) and the other as a client (initiating the request to connect to the server).

Once the two are connected, the communications between the server and host device are handled through a Bluetooth Socket at both ends.

To listen for incoming connection requests call the listenUsingRfcommWithServiceRecord method on your Bluetooth Adapter, passing in both a string "name" to identify your server and a UUID (universally unique identifier). This will return a BluetoothServerSocket object. Note that the client Bluetooth Socket that connects to this listener will need to know the UUID in order to connect.

To start listening for connections call accept on this Server Socket, optionally passing in a timeout duration. The Server Socket will now block until a remote Bluetooth Socket client with a matching UUID attempts to connect. If a connection request is made from a remote device that is not yet paired with the local adapter, the user will be prompted to accept a pairing request before the accept call returns. This prompt is made via a notification, as shown in Figure 13-3.

Figure 13-3. FIGURE 13-3

If an incoming connection request is successful, accept will return a Bluetooth Socket connected to the client device. You can use this socket to transfer data, as shown later in this section.

Note

Note that accept is a blocking operation, so it's best practice to listen for incoming connection requests on a background thread rather than block the UI thread until a connection has been made.

It's also important to note that your Bluetooth Adapter must be discoverable for remote Bluetooth Devices to connect to it. Listing 13-8 shows some typical skeleton code that uses the ACTION_REQUEST_DISCOVERABLE broadcast to request that the device be made discoverable, before listening for incoming connection requests for the returned discoverability duration.

Example 13-8. Listening for Bluetooth Socket connection requests

startActivityForResult(new
  Intent(BluetoothAdapter.ACTION_REQUEST_DISCOVERABLE),
         DISCOVERY_REQUEST);

@Override
protected void onActivityResult(int requestCode,
                                int resultCode, Intent data) {
  if (requestCode == DISCOVERY_REQUEST) {
    boolean isDiscoverable = resultCode > 0;
    int discoverableDuration = resultCode;
    if (isDiscoverable) {
      UUID uuid = UUID.fromString("a60f35f0-b93a-11de-8a39-08002009c666");
      String name = "bluetoothserver";

      final BluetoothServerSocket btserver =
        bluetooth.listenUsingRfcommWithServiceRecord(name, uuid);

      Thread acceptThread = new Thread(new Runnable() {
        public void run() {
          try {
            // Block until client connection established.
            BluetoothSocket serverSocket = btserver.accept();
            // TODO Transfer data using the server socket
          } catch (IOException e) {
            Log.d("BLUETOOTH", e.getMessage());
          }
        }
      });
      acceptThread.start();
    }
  }
}

BluetoothDevice device = bluetooth.getRemoteDevice("01:23:77:35:2F:AA");

Set<BluetoothDevice> bondedDevices = bluetooth.getBondedDevices();
if (bondedDevices.contains(remoteDevice))
  // TODO Target device is bonded / paired with the local device.

final BluetoothDevice device =
bluetooth.getRemoteDevice("01:23:77:35:2F:AA");
final Set<BluetoothDevice> bondedDevices = bluetooth.getBondedDevices();

BroadcastReceiver discoveryResult = new BroadcastReceiver() {
@Override
public void onReceive(Context context, Intent intent) {
  BluetoothDevice remoteDevice =
    intent.getParcelableExtra(BluetoothDevice.EXTRA_DEVICE);

    if ((remoteDevice.equals(device) &&
        (bondedDevices.contains(remoteDevice)) {
      // TODO Target device is paired and discoverable
    }
};
registerReceiver(discoveryResult,
                 new IntentFilter(BluetoothDevice.ACTION_FOUND));

if (!bluetooth.isDiscovering())
  bluetooth.startDiscovery();

Opening a Client Bluetooth Socket Connection

To initiate a communications channel to a remote device, create a Bluetooth Socket from the BluetoothDevice object that represents it.

To create a new connection call createRfcommSocketToServiceRecord on the Bluetooth Device to connect to, passing in the UUID of the Bluetooth Server Socket accepting requests.

If you attempt to connect to a Bluetooth Device that has not yet been paired (bonded) with the host device, you will be prompted to accept the pairing before the connect call completes, as shown in Figure 13-4.

Figure 13-4. FIGURE 13-4

The user must accept the pairing request on both the host and remote devices for the connection to be established.

The returned Bluetooth Socket can then be used to initiate the connection with a call to connect, as shown in Listing 13-10.

Note

Note that connect is a blocking operation, so it's best practice to initiate connection requests on a background thread rather than block the UI thread until a connection has been made.

Example 13-10. Connecting to a remote Bluetooth server

Try{
  BluetoothDevice device = bluetooth.getRemoteDevice("00:23:76:35:2F:AA");
  BluetoothSocket clientSocket =
    device.createRfcommSocketToServiceRecord(uuid);
  clientSocket.connect();
  // TODO Transfer data using the Bluetooth Socket
} catch (IOException e) {
  Log.d("BLUETOOTH", e.getMessage());
}

private void sendMessage(String message){
  OutputStream outStream;
  try {
    outStream = socket.getOutputStream();

    // Add a stop character.
    byte[] byteArray = (message + " ").getBytes();
    byteArray[byteArray.length − 1] = 0;

    outStream.write(byteArray);
  } catch (IOException e) { }
}

private String listenForMessage()
  String result = "";
  int bufferSize = 1024;
  byte[] buffer = new byte[bufferSize];

  try {
    InputStream instream = socket.getInputStream();
    int bytesRead = −1;

    while (true) {
      bytesRead = instream.read(buffer);
      if (bytesRead != −1) {
        while ((bytesRead == bufferSize) && (buffer[bufferSize-1] != 0)){
          message = message + new String(buffer, 0, bytesRead);
          bytesRead = instream.read(buffer);
        }
        message = message + new String(buffer, 0, bytesRead − 1);
           return result;
      }
    }

} catch (IOException e) {}

  return result;
}

The following example uses the Android Bluetooth APIs to construct a simple peer-to-peer messaging system that works between two paired Bluetooth devices.

Unfortunately the Android emulator can't currently be used to test Bluetooth functionality. In order to test this application you will need to have two physical devices.

If you run the application now, you should be able to configure one device to listen for a connection, use a second device to connect to it — and then, once connected, send simple text messages between the devices.

Note that this example has been kept as simple as possible to highlight the Bluetooth functionality being described. A better implementation would move all the connection state and logic code into a Service, as well as unregistering Broadcast Receivers once discovery and pairing had been completed.

The ConnectivityManager represents the Network Connectivity Service. It's used to monitor the state of network connections, configure failover settings, and control the network radios.

To access the Connectivity Manager, use getSystemService, passing in Context.CONNECTIVITY_SERVICE as the service name, as shown in Listing 13-12.

String service =
Context.CONNECTIVITY_SERVICE;ConnectivityManager connectivity =
  (ConnectivityManager)getSystemService(service);

To use the Connectivity Manager, your application needs read and write network state access permissions. Add each to your manifest, as shown here:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE"/>

One of the most important pieces of information available via the Connectivity Manager is the user's preference for background data transfers.

Users can elect to enable or disable background data transfers through the Settings

Figure 13-6. FIGURE 13-6

This value is enforced at the application level, meaning that you are responsible for reading the value and adhering to the user's preference for allowing background data transfers.

To obtain the background data setting, call the getBackgroundDataSetting method on the Connectivity Manager object:

boolean backgroundEnabled = connectivity.getBackgroundDataSetting();

If the background data setting is disabled, your application should transfer data only when it is active and in the foreground. By turning this value off, the user explicitly requests that your application not transfer data when it is not visible and in the foreground.

If your application requires background data transfer to function, it's best practice to notify users of this requirement and offer to take them to the settings page to alter their preference.

If the user does change the background data preference, the system will send a broadcast Intent with the ConnectivityManager.ACTION_BACKGROUND_DATA_SETTING_CHANGED action.

To monitor changes in the background data setting, create and register a new Broadcast Receiver that listens for this broadcast Intent, as shown in Listing 13-13.

registerReceiver(
  new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
      // Do something when the background data setting changes.
    },
  new IntentFilter(ConnectivityManager.ACTION_BACKGROUND_DATA_SETTING_CHANGED));

The Connectivity Manager provides a high-level view of the available network connections. Using the getActiveNetworkInfo or getNetworkInfo methods, as shown in Listing 13-14, returns NetworkInfo objects that include details on the currently active network or on an inactive network of the type specified.

Use the returned NetworkInfo details to find the connection status, network type, and detailed state information of the returned network.

// Get the active network information.
NetworkInfo activeNetwork = connectivity.getActiveNetworkInfo();
int networkType = networkInfo.getType();
switch (networkType) {
  case (ConnectivityManager.TYPE_MOBILE) : break;
  case (ConnectivityManager.TYPE_WIFI) : break;
  default: break;
}

// Get the mobile network information.
int network = ConnectivityManager.TYPE_MOBILE;
NetworkInfo mobileNetwork = connectivity.getNetworkInfo(network);

NetworkInfo.State state = mobileNetwork.getState();
NetworkInfo.DetailedState detailedState = mobileNetwork.getDetailedState();

The Connectivity Manager can also be used to control network hardware and configure failover preferences.

Android will attempt to connect to the preferred network whenever an authorized application requests an Internet connection. You can find the current, and set the preferred, network using the getNetworkPreference and setNetworkPreference methods, respectively, as shown in the following code snippet:

int networkPreference = connectivity.getNetworkPreference();
connectivity.setNetworkPreference(NetworkPreference.PREFER_WIFI);

If the preferred connection is unavailable, or connectivity on this network is lost, Android will automatically attempt to connect to the secondary network.

You can control the availability of the network types using the setRadio method. This method lets you set the state of the radio associated with a particular network (Wi-Fi, mobile, etc.). For example, in the following code snippet the Wi-Fi radio is turned off and the mobile radio is turned on:

connectivity.setRadio(NetworkType.WIFI, false);
connectivity.setRadio(NetworkType.MOBILE, true);

One of the most useful functions of the Connectivity Manager is to notify applications of changes in network connectivity.

To monitor network connectivity create your own Broadcast Receiver implementation that listens for ConnectivityManager.CONNECTIVITY_ACTION broadcast Intents. Such Intents include several extras that provide additional details on the change to the connectivity state. You can access each extra using one of the static constants available from the ConnectivityManager class:

The Wi-Fi Manager broadcasts Intents whenever the connectivity status of the Wi-Fi network changes, using an action from one of the following constants defined in the WifiManager class:

Once an active network connection has been established, use the getConnectionInfo method on the Wi-Fi Manager to find information on the active connection's status. The returned WifiInfo object includes the SSID, BSSID, Mac address, and IP address of the current access point, as well as the current link speed and signal strength.

Listing 13-17 queries the active Wi-Fi connection.

WifiInfo info = wifi.getConnectionInfo();
if (info.getBSSID() != null) {
  int strength = WifiManager.calculateSignalLevel(info.getRssi(), 5);
  int speed = info.getLinkSpeed();
  String units = WifiInfo.LINK_SPEED_UNITS;
  String ssid = info.getSSID();

  String cSummary = String.format("Connected to %s at %s%s. Strength %s/5",
                                   ssid, speed, units, strength);
}

You can also use the Wi-Fi Manager to conduct access point scans using the startScan method.

An Intent with the SCAN_RESULTS_AVAILABLE_ACTION action will be broadcast to asynchronously announce that the scan is complete and results are available.

Call getScanResults to get those results as a list of ScanResult objects.

Each Scan Result includes the details retrieved for each access point detected, including link speed, signal strength, SSID, and the authentication techniques supported.

Listing 13-18 shows how to initiate a scan for access points that displays a Toast indicating the total number of access points found and the name of the access point with the strongest signal.

// Register a broadcast receiver that listens for scan results.
registerReceiver(new BroadcastReceiver() {
  @Override
  public void onReceive(Context context, Intent intent) {
    List<ScanResult> results = wifi.getScanResults();
    ScanResult bestSignal = null;
    for (ScanResult result : results) {
      if (bestSignal == null ||
          WifiManager.compareSignalLevel(bestSignal.level,result.level)<0)
        bestSignal = result;
    }

    String toastText = String.format("%s networks found. %s is
                                     the strongest.",
                                     results.size(), bestSignal.SSID);

    Toast.makeText(getApplicationContext(), toastText, Toast.LENGTH_LONG);
  }
}, new IntentFilter(WifiManager.SCAN_RESULTS_AVAILABLE_ACTION));

// Initiate a scan.
wifi.startScan();

You can use the Wi-Fi Manager to manage the configured network settings and control which networks to connect to. Once connected, you can interrogate the active network connection to get additional details of its configuration and settings.

Get a list of the current network configurations using getConfiguredNetworks. The list of WifiConfiguration objects returned includes the network ID, SSID, and other details for each configuration.

To use a particular network configuration, use the enableNetwork method, passing in the network ID to use and specifying true for the disableAllOthers parameter, as shown in Listing 13-19.

// Get a list of available configurations
List<WifiConfiguration> configurations = wifi.getConfiguredNetworks();
// Get the network ID for the first one.
if (configurations.size() > 0) {
  int netID = configurations.get(0).networkId;
  // Enable that network.
  boolean disableAllOthers = true;
  wifi.enableNetwork(netID, disableAllOtherstrue);
}

To connect to a Wi-Fi network you need to create and register a configuration. Normally, your users would do this using the native Wi-Fi configuration settings, but there's no reason you can't expose the same functionality within your own applications, or for that matter replace the native Wi-Fi configuration Activity entirely.

Network configurations are stored as WifiConfiguration objects. The following is a non-exhaustive list of some of the public fields available for each Wi-Fi configuration:

The configuration object also contains the supported authentication techniques, as well as the keys used previously to authenticate with this access point.

The addNetwork method lets you specify a new configuration to add to the current list; similarly, updateNetwork lets you update a network configuration by passing in a WifiConfiguration that's sparsely populated with a network ID and the values you want to change.

You can also use removeNetwork, passing in a network ID, to remove a configuration.

To persist any changes made to the network configurations, you must call saveConfiguration.