From 1362bbcf760bd55d325d00ddea4b6f76afad8c08 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Wed, 16 Dec 2009 18:32:55 -0800 Subject: [PATCH] docs: update the Bluetooth guide with links to the sample app, scrub the sibling files, and revise the Bluetooth package summary to point to the BT dev guide. --- core/java/android/bluetooth/package.html | 90 ++------------------ docs/html/guide/topics/wireless/bluetooth.jd | 11 ++- docs/html/guide/topics/wireless/index.jd | 12 ++- docs/html/guide/topics/wireless/wifi.jd | 2 +- 4 files changed, 24 insertions(+), 91 deletions(-) diff --git a/core/java/android/bluetooth/package.html b/core/java/android/bluetooth/package.html index 4f0755e715083..5ff240c706ca1 100644 --- a/core/java/android/bluetooth/package.html +++ b/core/java/android/bluetooth/package.html @@ -12,96 +12,16 @@ devices, connecting with devices, and managing data transfer between devices.
  • Transfer data to and from other devices
    • -

    Note: +

    To perform Bluetooth communication using these APIs, an application must declare the {@link android.Manifest.permission#BLUETOOTH} permission. Some -additional functionality, such as requesting device discovery and -pairing also requires the {@link android.Manifest.permission#BLUETOOTH_ADMIN} +additional functionality, such as requesting device discovery, +also requires the {@link android.Manifest.permission#BLUETOOTH_ADMIN} permission.

    -

    Overview

    - -

    Here's a basic introduction to the Bluetooth classes:

    -
    -
    {@link android.bluetooth.BluetoothAdapter}
    -
    This represents the local Bluetooth adapter, which is essentially the - entry-point to performing any interaction with Bluetooth. With it, you can - discover other Bluetooth devices, query a list of bonded (paired) devices, - initialize a {@link android.bluetooth.BluetoothDevice} using a known MAC - address, and create a {@link android.bluetooth.BluetoothServerSocket} to - listen for communications from other devices.
    - -
    {@link android.bluetooth.BluetoothDevice}
    -
    This represents a remote Bluetooth device. Use this to request a - connection with a remote device through a - {@link android.bluetooth.BluetoothSocket} - or query information about the device such as its name, address, class, and - bonding state.
    - -
    {@link android.bluetooth.BluetoothSocket}
    -
    This represents the interface for a Bluetooth socket - (similar to a TCP client-side {@link java.net.Socket}). This is the - connection point that allows an app to transfer data with another Bluetooth - device via {@link java.io.InputStream} and {@link java.io.OutputStream}.
    -
    {@link android.bluetooth.BluetoothServerSocket}
    - -
    This represents an open server socket that listens for incoming requests - (similar to a TCP server-side {@link java.net.ServerSocket}). - When attempting to connect two Android devices, one device will need to open - a server socket with this class. When a connection is accepted, a new - {@link android.bluetooth.BluetoothSocket} will be returned, - which can be used to manage the connection and transfer data.
    - -
    {@link android.bluetooth.BluetoothClass}
    -
    This represents the Bluetooth class for a device which describes general - characteristics and capabilities of a device. This class and its subclasses - don't provide any actual functionality. The sub-classes are entirely composed - of constants for the device and service class definitions.
    -
    - - -

    Example Procedure

    - -

    For example, here's an pseudo-code procedure for discovering and -connecting a remote device, and transfering data:

    - -
      -
    1. Register a {@link android.content.BroadcastReceiver} that accepts the - {@link android.bluetooth.BluetoothDevice#ACTION_FOUND} Intent.
      2. -
    2. Call {@link android.bluetooth.BluetoothAdapter#getDefaultAdapter} to - retrieve the Android system's local - {@link android.bluetooth.BluetoothAdapter}.
      3. -
    3. Call {@link android.bluetooth.BluetoothAdapter#startDiscovery() - BluetoothAdapter.startDiscovery()} to scan for local devices. This is where - the BroadcastReceiver comes in; Android now scans for devices and will - broadcast the {@link android.bluetooth.BluetoothDevice#ACTION_FOUND} Intent - for each remote device discovered. The - {@link android.content.BroadcastReceiver} - you created will receive each Intent.
      4. -
    4. The {@link android.bluetooth.BluetoothDevice#ACTION_FOUND} Intent - includes the {@link android.bluetooth.BluetoothDevice#EXTRA_DEVICE} - Parcelable extra, which is a {@link android.bluetooth.BluetoothDevice} - object. Extract this from the Intent and call - {@link android.bluetooth.BluetoothDevice#createRfcommSocketToServiceRecord(java.util.UUID) - BluetoothDevice.createRfcommSocketToServiceRecord()} - to open a {@link android.bluetooth.BluetoothSocket} with a chosen - remote device.
      5. -
    5. Call {@link android.bluetooth.BluetoothSocket#connect() - BluetoothSocket.connect()} to connect with the remote device.
      6. -
    6. When successfully connected, call - {@link android.bluetooth.BluetoothSocket#getInputStream() - BluetoothSocket.getInputStream()} and/or - {@link android.bluetooth.BluetoothSocket#getOutputStream() - BluetoothSocket.getOutputStream()} to retreive an - {@link java.io.InputStream} and {@link java.io.OutputStream}, respectively, - which are hooked into the socket.
      7. -
    7. Use {@link java.io.InputStream#read(byte[]) InputStream.read()} and - {@link java.io.OutputStream#write(byte[]) OutputStream.write()} to transfer - data.
      8. -
    - - +

    For a detailed guide to using the Bluetooth APIs, see the Bluetooth Dev Guide topic.

    Note: Not all Android devices are guaranteed to have Bluetooth functionality.

    diff --git a/docs/html/guide/topics/wireless/bluetooth.jd b/docs/html/guide/topics/wireless/bluetooth.jd index 8a0efc9ac3d87..80aa0d734f517 100644 --- a/docs/html/guide/topics/wireless/bluetooth.jd +++ b/docs/html/guide/topics/wireless/bluetooth.jd @@ -34,6 +34,12 @@ page.title=Bluetooth
  • Managing a Connection
    • +

    See also

    +
      +
    1. Bluetooth Chat sample + app
      2. +
    + @@ -826,4 +832,7 @@ terminated at any time by closing the {@link android.bluetooth.BluetoothSocket}. This should always be called when you're done using the Bluetooth connection.

    - +
    +

    For a complete demonstration using the Bluetooth APIs, see the Bluetooth Chat sample app.

    +
    diff --git a/docs/html/guide/topics/wireless/index.jd b/docs/html/guide/topics/wireless/index.jd index a3a2b363f6aae..23d2f0fc4f788 100644 --- a/docs/html/guide/topics/wireless/index.jd +++ b/docs/html/guide/topics/wireless/index.jd @@ -1,8 +1,9 @@ page.title=Wireless Controls @jd:body +Go away. - + diff --git a/docs/html/guide/topics/wireless/wifi.jd b/docs/html/guide/topics/wireless/wifi.jd index 520feafe38a17..761e463f0dea7 100644 --- a/docs/html/guide/topics/wireless/wifi.jd +++ b/docs/html/guide/topics/wireless/wifi.jd @@ -15,4 +15,4 @@ parent.link=index.html -TODO \ No newline at end of file +Go away. \ No newline at end of file