BluetoothAdapter

版本：Android 2.3 r1

结构

继承关系

public final class BluetoothAdapter extends Object

java.lang.Object

android.bluetooth.BluetoothAdapter

类概述

代表本地的蓝牙适配器设备。BluetoothAdapter类让用户能执行基本的蓝牙任务。例如： 初始化设备的搜索，查询可匹配的设备集，使用一个已知的MAC地址来初始化一个BluetoothDevice类，创建一个 BluetoothServerSocket类以监听其它设备对本机的连接请求等。

为了得到这个代表本地蓝牙适配器的 BluetoothAdapter类，调用getDefaultAdapter()这一静态方法。这是所有蓝牙动作使用的第一步。当拥有本地适配器以后， 用户可以获得一系列的BluetoothDevice对象，这些对象代表所有拥有getBondedDevice()方法的已经匹配的设备；用 startDiscovery()方法来开始设备的搜寻；或者创建一个BluetoothServerSocket类，通过 listenUsingRfcommWithServiceRecord(String, UUID)方法来监听新来的连接请求。

Note：大部分方法需要BLUETOOTH权限，一些方法同时需要BLUETOOTH_ADMIN权限。

参见

                   BluetoothDevice

       BluetoothServerSocket

常量

         String      ACTION_DISCOVERY_FINISHED   

广播事件：本地蓝牙适配器已经完成设备的搜寻过程。

需要BLUETOOTH权限接收。

常量值: "android.bluetooth.adapter.action.DISCOVERY_FINISHED"

String      ACTION_DISCOVERY_STARTED    

广播事件：本地蓝牙适配器已经开始对远程设备的搜寻过程。

它通常牵涉到一个大概需时12秒的查询扫描过程，紧跟着是一个对每个获取到自身蓝牙名称的新设备的页面扫描。

         用户会发现一个把ACTION_FOUND常量通知为远程蓝牙设备的注册。
设备查找是一个重量级过程。当查找正在进行的时候，用户不能尝试对新的远程蓝牙设备进行连接，同时存在的连接将获得有限制的带宽以及高等待时间。用户可用cancelDiscovery()类来取消正在执行的查找进程。

需要BLUETOOTH权限接收。

常量值: "android.bluetooth.adapter.action.DISCOVERY_STARTED"

String      ACTION_LOCAL_NAME_CHANGED      

广播活动：本地蓝牙适配器已经更改了它的蓝牙名称。

该名称对远程蓝牙设备是可见的。

它总是包含了一个带有名称的EXTRA_LOCAL_NAME附加域。

需要BLUETOOTH权限接收。

常量值: "android.bluetooth.adapter.action.LOCAL_NAME_CHANGED"

String      ACTION_REQUEST_DISCOVERABLE      

Activity活动：显示一个请求被搜寻模式的系统活动。如果蓝牙模块当前未打开，该活动也将请求用户打开蓝牙模块。

被搜寻模式和SCAN_MODE_CONNECTABLE_DISCOVERABLE等价。当远程设备执行查找进程的时候，它允许其发现该蓝牙适配器。

从隐私安全考虑，Android不会将被搜寻模式设置为默认状态。

该意图的发送者可以选择性地运用EXTRA_DISCOVERABLE_DURATION这个附加域去请求发现设备的持续时间。普遍来说，对于每一请求，默认的持续时间为120秒，最大值则可达到300秒。

Android 运用onActivityResult(int, int, Intent)回收方法来传递该活动结果的通知。被搜寻的时间（以秒为单位）将通过resultCode值来显示，如果用户拒绝被搜寻，或者设备产生了错 误，则通过RESULT_CANCELED值来显示。

每当扫描模式变化的时候，应用程序可以为通过ACTION_SCAN_MODE_CHANGED值来监听全局的消息通知。比如，当设备停止被搜寻以后，该消息可以被系统通知給应用程序。

需要BLUETOOTH权限

常量值: "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE"

String      ACTION_REQUEST_ENABLE

Activity活动：显示一个允许用户打开蓝牙模块的系统活动。

当蓝牙模块完成打开工作，或者当用户决定不打开蓝牙模块时，系统活动将返回该值。

Android 运用onActivityResult(int, int, Intent)回收方法来传递该活动结果的通知。如果蓝牙模块被打开，将通过resultCode值RESULT_OK来显示；如果用户拒绝该请求，或者设备产生了错误，则通过RESULT_CANCELED值来显示。

         每当蓝牙模块被打开或者关闭，应用程序可以为通过ACTION_STATE_CHANGED值来监听全局的消息通知。

需要BLUETOOTH权限

常量值: "android.bluetooth.adapter.action.REQUEST_ENABLE"

String      ACTION_SCAN_MODE_CHANGED        

广播活动：指明蓝牙扫描模块或者本地适配器已经发生变化

它总是包含EXTRA_SCAN_MODE和EXTRA_PREVIOUS_SCAN_MODE。这两个附加域各自包含了新的和旧的扫描模式。

需要BLUETOOTH权限

常量值: "android.bluetooth.adapter.action.SCAN_MODE_CHANGED"

String      ACTION_STATE_CHANGED   

广播活动：本来的蓝牙适配器的状态已经改变。

例如：蓝牙模块已经被打开或者关闭。

它总是包含EXTRA_STATE和EXTRA_PREVIOUS_STATE。这两个附加域各自包含了新的和旧的状态。

需要BLUETOOTH权限接收

常量值: "android.bluetooth.adapter.action.STATE_CHANGED"

int   ERROR   

标记该类的错误值。确保和该类中的任意其它整数常量不相等。它为需要一个标记错误值的函数提供了便利。例如：

Intent.getIntExtra(BluetoothAdapter.EXTRA_STATE, BluetoothAdapter.ERROR)

常量值: -2147483648 (0x80000000)

String      EXTRA_DISCOVERABLE_DURATION     

试图在ACTION_REQUEST_DISCOVERABLE常量中作为一个可选的整型附加域，来为短时间内的设备发现请求一个特定的持续时间。默认值为120秒，超过300秒的请求将被限制。这些值是可以变化的。

常量值: "android.bluetooth.adapter.extra.DISCOVERABLE_DURATION"

String      EXTRA_LOCAL_NAME   

试图在ACTION_LOCAL_NAME_CHANGED常量中作为一个字符串附加域，来请求本地蓝牙的名称。

常量值: "android.bluetooth.adapter.extra.LOCAL_NAME"

String      EXTRA_PREVIOUS_SCAN_MODE  

试图在ACTION_SCAN_MODE_CHANGED常量中作为一个整型附加域，来请求以前的扫描模式。可能值有: SCAN_MODE_NONE, SCAN_MODE_CONNECTABLE, SCAN_MODE_CONNECTABLE_DISCOVERABLE

常量值: "android.bluetooth.adapter.extra.PREVIOUS_SCAN_MODE"

String      EXTRA_PREVIOUS_STATE      

试图在ACTION_STATE_CHANGED常量中作为一个整型附加域，来请求以前的供电状态。 可能值有: STATE_OFF, STATE_TURNING_ON, STATE_ON, STATE_TURNING_OFF

常量值: "android.bluetooth.adapter.extra.PREVIOUS_STATE"

String      EXTRA_SCAN_MODE     

试图在ACTION_SCAN_MODE_CHANGED常量中作为一个整型附加域，来请求当前的扫描模式.可能值有: SCAN_MODE_NONE, SCAN_MODE_CONNECTABLE, SCAN_MODE_CONNECTABLE_DISCOVERABLE

常量值: "android.bluetooth.adapter.extra.SCAN_MODE"

String      EXTRA_STATE         

试图在ACTION_STATE_CHANGED常量中作为一个整型附加域，来请求当前的供电状态。 可能值有: STATE_OFF, STATE_TURNING_ON, STATE_ON, STATE_TURNING_OFF

常量值: "android.bluetooth.adapter.extra.STATE"

int   SCAN_MODE_CONNECTABLE       

指明在本地蓝牙适配器中，查询扫描功能失效，但页面扫描功能有效。因此该设备不能被远程蓝牙设备发现，但如果以前曾经发现过该设备，则远程设备可以对其进行连接。

常量值: 21 (0x00000015)

int   SCAN_MODE_CONNECTABLE_DISCOVERABLE    

指明在本地蓝牙适配器中，查询扫描功能和页面扫描功能都有效。因此该设备既可以被远程蓝牙设备发现，也可以被其连接。

常量值: 23 (0x00000017)

int   SCAN_MODE_NONE      

指明在本地蓝牙适配器中，查询扫描功能和页面扫描功能都失效. 因此该设备既不可以被远程蓝牙设备发现，也不可以被其连接。

常量值: 20 (0x00000014)

int   STATE_OFF     

指明本地蓝牙适配器模块已经关闭

常量值: 10 (0x0000000a)

int   STATE_ON      

指明本地蓝牙适配器模块已经打开，并且准备被使用。

常量值: 12 (0x0000000c)

int   STATE_TURNING_OFF   

指明本地蓝牙适配器模块正在关闭。本地客户端可以立刻尝试友好地断开任意外部连接。

常量值: 13 (0x0000000d)

int   STATE_TURNING_ON    

指明本地蓝牙适配器模块正在打开. 然而本地客户在尝试使用这个适配器之前需要为STATE_ON状态而等待。

常量值: 11 (0x0000000b)

公共方法

public boolean cancelDiscovery ()

取消当前的设备发现查找进程

需要BLUETOOTH_ADMIN权限。

因为对蓝牙适配器而言，查找是一个重量级的过程，因此这个方法必须在尝试连接到远程设备前使用用connect()方法进行调用。发现的过程不会由活动来进行管理，但是它会作为一个系统服务来运行，因此即使它不能直接请求这样的一个查询动作，也必需取消该搜索进程。

如果蓝牙状态不是STATE_ON，这个API将返回false。蓝牙打开后，等待ACTION_STATE_CHANGED更新成STATE_ON。

返回值

成功则返回true，有错误则返回false。

public static boolean checkBluetoothAddress (String address)

验证皆如"00:43:A8:23:10:F0"之类的蓝牙地址。

字母必须为大写才有效。

参数

address 字符串形式的蓝牙模块地址

返回值

地址正确则返回true，否则返回false。

public boolean disable ()

关闭本地蓝牙适配器—不能在没有明确关闭蓝牙的用户动作中使用。

这个方法友好地停止所有的蓝牙连接，停止蓝牙系统服务，以及对所有基础蓝牙硬件进行断电。

没有用户的直接同意，蓝牙永远不能被禁止。这个disable()方法只提供了一个应用，该应用包含了一个改变系统设置的用户界面（例如“电源控制”应用）。

这 是一个异步调用方法：该方法将马上获得返回值，用户要通过监听ACTION_STATE_CHANGED值来获取随后的适配器状态改变的通知。如果该调用 返回true值，则该适配器状态会立刻从STATE_ON转向STATE_TURNING_OFF，稍后则会转为STATE_OFF或者 STATE_ON。如果该调用返回false，那么系统已经有一个保护蓝牙适配器被关闭的问题—比如该适配器已经被关闭了。

需要BLUETOOTH_ADMIN权限。

                   返回值

如果蓝牙适配器的停止进程已经开启则返回true，如果产生错误则返回false。

public boolean enable ()

         打开本地蓝牙适配器—不能在没有明确打开蓝牙的用户动作中使用。

该方法将为基础的蓝牙硬件供电，并且启动所有的蓝牙系统服务。

没有用户的直接同意，蓝牙永远不能被禁止。如果用户为了创建无线连接而打开了蓝牙模块，则其需要ACTION_REQUEST_ENABLE值，该值将提出 一个请求用户允许以打开蓝牙模块的会话。这个enable()值只提供了一个应用，该应用包含了一个改变系统设置的用户界面（例如“电源控制”应用）。

这是一个异步调用方法：该方法将马上获得返回值，用户要通过监听ACTION_STATE_CHANGED值来获取随后的适配器状态改变的通知。如果该调用 返回true值，则该适配器状态会立刻从STATE_OFF转向STATE_TURNING_ON，稍后则会转为STATE_OFF或者 STATE_ON。如果该调用返回false，那么说明系统已经有一个保护蓝牙适配器被打开的问题—比如飞行模式，或者该适配器已经被打开。

需要BLUETOOTH_ADMIN权限。

返回值    

如果蓝牙适配器的打开进程已经开启则返回true，如果产生错误则返回false。

public String getAddress ()

返回本地蓝牙适配器的硬件地址

例如： "00:11:22:AA:BB:CC"

需要BLUETOOTH权限。

返回值    

字符串形式的蓝牙模块地址

public Set<BluetoothDevice> getBondedDevices ()

返回已经匹配到本地适配器的BluetoothDevice类的对象集合

如果蓝牙状态不是STATE_ON，这个API将返回false。蓝牙打开后，等待ACTION_STATE_CHANGED更新成STATE_ON。

需要BLUETOOTH权限。

返回值

未被修改的BluetoothDevice类的对象集合，如果有错误则返回null。

public static synchronized BluetoothAdapter getDefaultAdapter ()

获取对默认本地蓝牙适配器的的操作权限。

目前Andoird只支持一个蓝牙适配器，但是API可以被扩展为支持多个适配器。该方法总是返回默认的适配器。

返回值

返回默认的本地适配器，如果蓝牙适配器在该硬件平台上不能被支持，则返回null。

public String getName ()

获取本地蓝牙适配器的蓝牙名称

这个名称对于外界蓝牙设备而言是可见的。

需要BLUETOOTH权限。

返回值

该蓝牙适配器名称，如果有错误则返回null

public BluetoothDevice getRemoteDevice (String address)

为给予的蓝牙硬件地址获取一个BluetoothDevice对象。

         合法的蓝牙硬件地址必须为大写，格式类似于"00:11:22:33:AA:BB"。checkBluetoothAddress(String)方法可以用来验证蓝牙地址的正确性。

BluetoothDevice类对于合法的硬件地址总会产生返回值，即使这个适配器从未见过该设备。

参数

address 合法的蓝牙MAC地址

异常

IllegalArgumentException      如果地址不合法

public int getScanMode ()

获取本地蓝牙适配器的当前蓝牙扫描模式

蓝牙扫描模式决定本地适配器可连接并且/或者可被远程蓝牙设备所连接。

可能值有: SCAN_MODE_NONE, SCAN_MODE_CONNECTABLE, SCAN_MODE_CONNECTABLE_DISCOVERABLE.

如果蓝牙状态不是STATE_ON，这个API将返回false。蓝牙打开后，等待ACTION_STATE_CHANGED更新成STATE_ON。

需要BLUETOOTH权限。

         返回值

扫描模式

public int getState ()

获取本地蓝牙适配器的当前状态

可能值有 STATE_OFF, STATE_TURNING_ON, STATE_ON, STATE_TURNING_OFF.
需要BLUETOOTH类

需要BLUETOOTH权限。

                   返回值

current state of Bluetooth adapter

public boolean isDiscovering ()

如果当前蓝牙适配器正处于设备发现查找进程中，则返回真值

设备查找是一个重量级过程。当查找正在进行的时候，用户不能尝试对新的远程蓝牙设备进行连接，同时存在的连接将获得有限制的带宽以及高等待时间。用户可用cencelDiscovery()类来取消正在执行的查找进程。

应用程序也可以为ACTION_DISCOVERY_STARTED或者ACTION_DISCOVERY_FINISHED进行注册，从而当查找开始或者完成的时候，可以获得通知。

如果蓝牙状态不是STATE_ON，这个API将返回false。蓝牙打开后，等待ACTION_STATE_CHANGED更新成STATE_ON。

需要BLUETOOTH权限。

                   返回值

如果正在查找，则返回true

public boolean isEnabled ()

如果蓝牙正处于打开状态并可用，则返回真值

与getBluetoothState()==STATE_ON 等价

需要BLUETOOTH权限。

                   返回值

如果本地适配器已经打开，则返回true

public BluetoothServerSocket listenUsingRfcommWithServiceRecord (String name, UUID uuid)

创建一个正在监听的安全的带有服务记录的无线射频通信（RFCOMM）蓝牙端口。

一个对该端口进行连接的远程设备将被认证，对该端口的通讯将被加密。

使用accpet（）方法可以获取从监听BluetoothServerSocket处新来的连接

该系统分配一个未被使用的无线射频通信通道来进行监听。

该系统也将注册一个服务探索协议（SDP）记录，该记录带有一个包含了特定 的通用唯一识别码（Universally Unique Identifier，UUID），服务器名称和自动分配通道的本地SDP服务。远程蓝牙设备可以用相同的UUID来查询自己的SDP服务器，并搜寻连接 到了哪个通道上。如果该端口已经关闭，或者如果该应用程序异常退出，则这个SDP记录会被移除。

使用createRfcommSocketToServiceRecord(UUID)从另一使用相同UUID的设备来连接到这个端口

需要BLUETOOTH权限。

参数

name       SDP记录下的服务器名

uuid         SDP记录下的UUID

                   返回值

一个正在监听的无线射频通信蓝牙服务端口

异常

IOException    产生错误，比如蓝牙设备不可用，或者许可无效，或者通道被占用。

public boolean setName (String name)

设置蓝牙或者本地蓝牙适配器的昵称.

这个名字对于外界蓝牙设备而言是可见的。

合法的蓝牙名称最多拥有248位UTF-8字符，但是很多外界设备只能显示前40个字符，有些可能只限制前20个字符。

如果蓝牙状态不是STATE_ON，这个API将返回false。蓝牙打开后，等待ACTION_STATE_CHANGED更新成STATE_ON。

需要BLUETOOTH_ADMIN权限。

参数

name       一个合法的蓝牙名称

返回值

如果该名称已被设定，则返回true，否则返回false

public boolean startDiscovery ()

开始对远程设备进行查找的进程

它通常牵涉到一个大概需时12秒的查询扫描过程，紧跟着是一个对每个获取到自身蓝牙名称的新设备的页面扫描。

这是一个异步调用方法：该方法将马上获得返回值，注册ACTION_DISCOVERY_STARTED and ACTION_DISCOVERY_FINISHED意图准确地确定该探索是处于开始阶段或者完成阶段。注册ACTION_FOUND以活动远程蓝牙设备 已找到的通知。

设备查找是一个重量级过程。当查找正在进行的时候，用户不能尝试对新的远程蓝牙设备进行连接，同时存在的连接将获得有限制的带宽以 及高等待时间。用户可用cencelDiscovery()类来取消正在执行的查找进程。发现的过程不会由活动来进行管理，但是它会作为一个系统服务来运 行，因此即使它不能直接请求这样的一个查询动作，也必需取消该搜索进程。

设备搜寻只寻找已经被连接的远程设备。许多蓝牙设备默认不会被搜寻到，并且需要进入到一个特殊的模式当中。

如果蓝牙状态不是STATE_ON，这个API将返回false。蓝牙打开后，等待ACTION_STATE_CHANGED更新成STATE_ON。

需要BLUETOOTH_ADMIN权限。

返回值

成功返回true，错误返回false。

补充

         文章精选

                   Android蓝牙开发浅谈

                   Android蓝牙API之BluetoothAdapter类(1)

                   Android蓝牙API之BluetoothAdapter类(2)

                   Ophone平台蓝牙编程基础