BluetoothAdapter

版本：Android 2.3 r1

?

結構

繼承關系

public final class BluetoothAdapter extends Object

????????

java.lang.Object

android.bluetooth.BluetoothAdapter

?

類概述

代表本地的藍牙適配器設備。BluetoothAdapter類讓用戶能執(zhí)行基本的藍牙任務。例如： 初始化設備的搜索，查詢可匹配的設備集，使用一個已知的MAC地址來初始化一個BluetoothDevice類，創(chuàng)建一個 BluetoothServerSocket類以監(jiān)聽其它設備對本機的連接請求等。

為了得到這個代表本地藍牙適配器的 BluetoothAdapter類，調用getDefaultAdapter()這一靜態(tài)方法。這是所有藍牙動作使用的第一步。當擁有本地適配器以后， 用戶可以獲得一系列的BluetoothDevice對象，這些對象代表所有擁有getBondedDevice()方法的已經匹配的設備；用 startDiscovery()方法來開始設備的搜尋；或者創(chuàng)建一個BluetoothServerSocket類，通過 listenUsingRfcommWithServiceRecord(String, UUID)方法來監(jiān)聽新來的連接請求。

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

參見

?????????????????? BluetoothDevice

?????? BluetoothServerSocket

?

常量

???????? String ???? ACTION_DISCOVERY_FINISHED ??

廣播事件：本地藍牙適配器已經完成設備的搜尋過程。

需要BLUETOOTH權限接收。

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

?

String ???? ACTION_DISCOVERY_STARTED ???

廣播事件：本地藍牙適配器已經開始對遠程設備的搜尋過程。

它通常牽涉到一個大概需時12秒的查詢掃描過程，緊跟著是一個對每個獲取到自身藍牙名稱的新設備的頁面掃描。

???????? 用戶會發(fā)現(xiàn)一個把ACTION_FOUND常量通知為遠程藍牙設備的注冊。
設備查找是一個重量級過程。當查找正在進行的時候，用戶不能嘗試對新的遠程藍牙設備進行連接，同時存在的連接將獲得有限制的帶寬以及高等待時間。用戶可用cancelDiscovery()類來取消正在執(zhí)行的查找進程。

需要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活動：顯示一個請求被搜尋模式的系統(tǒng)活動。如果藍牙模塊當前未打開，該活動也將請求用戶打開藍牙模塊。

被搜尋模式和SCAN_MODE_CONNECTABLE_DISCOVERABLE等價。當遠程設備執(zhí)行查找進程的時候，它允許其發(fā)現(xiàn)該藍牙適配器。

從隱私安全考慮，Android不會將被搜尋模式設置為默認狀態(tài)。

該意圖的發(fā)送者可以選擇性地運用EXTRA_DISCOVERABLE_DURATION這個附加域去請求發(fā)現(xiàn)設備的持續(xù)時間。普遍來說，對于每一請求，默認的持續(xù)時間為120秒，最大值則可達到300秒。

Android 運用onActivityResult(int, int, Intent)回收方法來傳遞該活動結果的通知。被搜尋的時間（以秒為單位）將通過resultCode值來顯示，如果用戶拒絕被搜尋，或者設備產生了錯 誤，則通過RESULT_CANCELED值來顯示。

每當掃描模式變化的時候，應用程序可以為通過ACTION_SCAN_MODE_CHANGED值來監(jiān)聽全局的消息通知。比如，當設備停止被搜尋以后，該消息可以被系統(tǒng)通知給應用程序。

需要BLUETOOTH權限

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

?

String ???? ACTION_REQUEST_ENABLE

Activity活動：顯示一個允許用戶打開藍牙模塊的系統(tǒng)活動。

當藍牙模塊完成打開工作，或者當用戶決定不打開藍牙模塊時，系統(tǒng)活動將返回該值。

Android 運用onActivityResult(int, int, Intent)回收方法來傳遞該活動結果的通知。如果藍牙模塊被打開，將通過resultCode值RESULT_OK來顯示；如果用戶拒絕該請求，或者設備產生了錯誤，則通過RESULT_CANCELED值來顯示。

???????? 每當藍牙模塊被打開或者關閉，應用程序可以為通過ACTION_STATE_CHANGED值來監(jiān)聽全局的消息通知。

需要BLUETOOTH權限

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

?

String ???? ACTION_SCAN_MODE_CHANGED ???????

廣播活動：指明藍牙掃描模塊或者本地適配器已經發(fā)生變化

它總是包含EXTRA_SCAN_MODE和EXTRA_PREVIOUS_SCAN_MODE。這兩個附加域各自包含了新的和舊的掃描模式。

需要BLUETOOTH權限

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

?

String ???? ACTION_STATE_CHANGED ??

廣播活動：本來的藍牙適配器的狀態(tài)已經改變。

例如：藍牙模塊已經被打開或者關閉。

它總是包含EXTRA_STATE和EXTRA_PREVIOUS_STATE。這兩個附加域各自包含了新的和舊的狀態(tài)。

需要BLUETOOTH權限接收

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

?

int ? ERROR ??

標記該類的錯誤值。確保和該類中的任意其它整數(shù)常量不相等。它為需要一個標記錯誤值的函數(shù)提供了便利。例如：

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

常量值: -2147483648 (0x80000000)

?

String ???? EXTRA_DISCOVERABLE_DURATION ????

試圖在ACTION_REQUEST_DISCOVERABLE常量中作為一個可選的整型附加域，來為短時間內的設備發(fā)現(xiàn)請求一個特定的持續(xù)時間。默認值為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常量中作為一個整型附加域，來請求以前的掃描模式?？赡苤涤?span lang="EN-US">: SCAN_MODE_NONE, SCAN_MODE_CONNECTABLE, SCAN_MODE_CONNECTABLE_DISCOVERABLE

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

?

String ???? EXTRA_PREVIOUS_STATE ?????

試圖在ACTION_STATE_CHANGED常量中作為一個整型附加域，來請求以前的供電狀態(tài)。 可能值有: 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常量中作為一個整型附加域，來請求當前的供電狀態(tài)。 可能值有: STATE_OFF, STATE_TURNING_ON, STATE_ON, STATE_TURNING_OFF

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

?

int ? SCAN_MODE_CONNECTABLE ??????

指明在本地藍牙適配器中，查詢掃描功能失效，但頁面掃描功能有效。因此該設備不能被遠程藍牙設備發(fā)現(xiàn)，但如果以前曾經發(fā)現(xiàn)過該設備，則遠程設備可以對其進行連接。

常量值: 21 (0x00000015)

?

int ? SCAN_MODE_CONNECTABLE_DISCOVERABLE ???

指明在本地藍牙適配器中，查詢掃描功能和頁面掃描功能都有效。因此該設備既可以被遠程藍牙設備發(fā)現(xiàn)，也可以被其連接。

常量值: 23 (0x00000017)

?

int ? SCAN_MODE_NONE ?????

指明在本地藍牙適配器中，查詢掃描功能和頁面掃描功能都失效. 因此該設備既不可以被遠程藍牙設備發(fā)現(xiàn)，也不可以被其連接。

常量值: 20 (0x00000014)

?

int ? STATE_OFF ????

指明本地藍牙適配器模塊已經關閉

常量值: 10 (0x0000000a)

?

int ? STATE_ON ?????

指明本地藍牙適配器模塊已經打開，并且準備被使用。

常量值: 12 (0x0000000c)

?

int ? STATE_TURNING_OFF ??

指明本地藍牙適配器模塊正在關閉。本地客戶端可以立刻嘗試友好地斷開任意外部連接。

常量值: 13 (0x0000000d)

?

int ? STATE_TURNING_ON ???

指明本地藍牙適配器模塊正在打開. 然而本地客戶在嘗試使用這個適配器之前需要為STATE_ON狀態(tài)而等待。

常量值: 11 (0x0000000b)

?

公共方法

public boolean cancelDiscovery ()

取消當前的設備發(fā)現(xiàn)查找進程

需要BLUETOOTH_ADMIN權限。

因為對藍牙適配器而言，查找是一個重量級的過程，因此這個方法必須在嘗試連接到遠程設備前使用用connect()方法進行調用。發(fā)現(xiàn)的過程不會由活動來進行管理，但是它會作為一個系統(tǒng)服務來運行，因此即使它不能直接請求這樣的一個查詢動作，也必需取消該搜索進程。

如果藍牙狀態(tài)不是STATE_ON，這個API將返回false。藍牙打開后，等待ACTION_STATE_CHANGED更新成STATE_ON。

返回值

成功則返回true，有錯誤則返回false。

?

public static boolean checkBluetoothAddress (String address)

驗證皆如"00:43:A8:23:10:F0"之類的藍牙地址。

字母必須為大寫才有效。

參數(shù)

address 字符串形式的藍牙模塊地址

返回值

地址正確則返回true，否則返回false。

?

public boolean disable ()

關閉本地藍牙適配器—不能在沒有明確關閉藍牙的用戶動作中使用。

這個方法友好地停止所有的藍牙連接，停止藍牙系統(tǒng)服務，以及對所有基礎藍牙硬件進行斷電。

沒有用戶的直接同意，藍牙永遠不能被禁止。這個disable()方法只提供了一個應用，該應用包含了一個改變系統(tǒng)設置的用戶界面（例如“電源控制”應用）。

這 是一個異步調用方法：該方法將馬上獲得返回值，用戶要通過監(jiān)聽ACTION_STATE_CHANGED值來獲取隨后的適配器狀態(tài)改變的通知。如果該調用 返回true值，則該適配器狀態(tài)會立刻從STATE_ON轉向STATE_TURNING_OFF，稍后則會轉為STATE_OFF或者 STATE_ON。如果該調用返回false，那么系統(tǒng)已經有一個保護藍牙適配器被關閉的問題—比如該適配器已經被關閉了。

需要BLUETOOTH_ADMIN權限。

?????????????????? 返回值

如果藍牙適配器的停止進程已經開啟則返回true，如果產生錯誤則返回false。

?

public boolean enable ()

???????? 打開本地藍牙適配器—不能在沒有明確打開藍牙的用戶動作中使用。

該方法將為基礎的藍牙硬件供電，并且啟動所有的藍牙系統(tǒng)服務。

沒有用戶的直接同意，藍牙永遠不能被禁止。如果用戶為了創(chuàng)建無線連接而打開了藍牙模塊，則其需要ACTION_REQUEST_ENABLE值，該值將提出 一個請求用戶允許以打開藍牙模塊的會話。這個enable()值只提供了一個應用，該應用包含了一個改變系統(tǒng)設置的用戶界面（例如“電源控制”應用）。

這是一個異步調用方法：該方法將馬上獲得返回值，用戶要通過監(jiān)聽ACTION_STATE_CHANGED值來獲取隨后的適配器狀態(tài)改變的通知。如果該調用 返回true值，則該適配器狀態(tài)會立刻從STATE_OFF轉向STATE_TURNING_ON，稍后則會轉為STATE_OFF或者 STATE_ON。如果該調用返回false，那么說明系統(tǒng)已經有一個保護藍牙適配器被打開的問題—比如飛行模式，或者該適配器已經被打開。

需要BLUETOOTH_ADMIN權限。

返回值????

如果藍牙適配器的打開進程已經開啟則返回true，如果產生錯誤則返回false。

?

public String getAddress ()

返回本地藍牙適配器的硬件地址

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

需要BLUETOOTH權限。

返回值????

字符串形式的藍牙模塊地址

?

public Set<BluetoothDevice> getBondedDevices ()

返回已經匹配到本地適配器的BluetoothDevice類的對象集合

如果藍牙狀態(tài)不是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類對于合法的硬件地址總會產生返回值，即使這個適配器從未見過該設備。

參數(shù)

address 合法的藍牙MAC地址

異常

IllegalArgumentException ???? 如果地址不合法

?

public int getScanMode ()

獲取本地藍牙適配器的當前藍牙掃描模式

藍牙掃描模式決定本地適配器可連接并且/或者可被遠程藍牙設備所連接。

可能值有: SCAN_MODE_NONE, SCAN_MODE_CONNECTABLE, SCAN_MODE_CONNECTABLE_DISCOVERABLE.

如果藍牙狀態(tài)不是STATE_ON，這個API將返回false。藍牙打開后，等待ACTION_STATE_CHANGED更新成STATE_ON。

需要BLUETOOTH權限。

???????? 返回值

掃描模式

?

public int getState ()

獲取本地藍牙適配器的當前狀態(tài)

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

需要BLUETOOTH權限。

?????????????????? 返回值

current state of Bluetooth adapter

?

public boolean isDiscovering ()

如果當前藍牙適配器正處于設備發(fā)現(xiàn)查找進程中，則返回真值

設備查找是一個重量級過程。當查找正在進行的時候，用戶不能嘗試對新的遠程藍牙設備進行連接，同時存在的連接將獲得有限制的帶寬以及高等待時間。用戶可用cencelDiscovery()類來取消正在執(zhí)行的查找進程。

應用程序也可以為ACTION_DISCOVERY_STARTED或者ACTION_DISCOVERY_FINISHED進行注冊，從而當查找開始或者完成的時候，可以獲得通知。

如果藍牙狀態(tài)不是STATE_ON，這個API將返回false。藍牙打開后，等待ACTION_STATE_CHANGED更新成STATE_ON。

需要BLUETOOTH權限。

?????????????????? 返回值

如果正在查找，則返回true

?

public boolean isEnabled ()

如果藍牙正處于打開狀態(tài)并可用，則返回真值

與getBluetoothState()==STATE_ON 等價

需要BLUETOOTH權限。

?????????????????? 返回值

如果本地適配器已經打開，則返回true

?

public BluetoothServerSocket listenUsingRfcommWithServiceRecord (String name, UUID uuid)

創(chuàng)建一個正在監(jiān)聽的安全的帶有服務記錄的無線射頻通信（RFCOMM）藍牙端口。

一個對該端口進行連接的遠程設備將被認證，對該端口的通訊將被加密。

使用accpet（）方法可以獲取從監(jiān)聽BluetoothServerSocket處新來的連接

該系統(tǒng)分配一個未被使用的無線射頻通信通道來進行監(jiān)聽。

該系統(tǒng)也將注冊一個服務探索協(xié)議（SDP）記錄，該記錄帶有一個包含了特定 的通用唯一識別碼（Universally Unique Identifier，UUID），服務器名稱和自動分配通道的本地SDP服務。遠程藍牙設備可以用相同的UUID來查詢自己的SDP服務器，并搜尋連接 到了哪個通道上。如果該端口已經關閉，或者如果該應用程序異常退出，則這個SDP記錄會被移除。

使用createRfcommSocketToServiceRecord(UUID)從另一使用相同UUID的設備來連接到這個端口

需要BLUETOOTH權限。

參數(shù)

name ????? SDP記錄下的服務器名

uuid ??????? SDP記錄下的UUID

?????????????????? 返回值

一個正在監(jiān)聽的無線射頻通信藍牙服務端口

異常

IOException ?? 產生錯誤，比如藍牙設備不可用，或者許可無效，或者通道被占用。

?

public boolean setName (String name)

設置藍牙或者本地藍牙適配器的昵稱.

這個名字對于外界藍牙設備而言是可見的。

合法的藍牙名稱最多擁有248位UTF-8字符，但是很多外界設備只能顯示前40個字符，有些可能只限制前20個字符。

如果藍牙狀態(tài)不是STATE_ON，這個API將返回false。藍牙打開后，等待ACTION_STATE_CHANGED更新成STATE_ON。

需要BLUETOOTH_ADMIN權限。

參數(shù)

name ????? 一個合法的藍牙名稱

返回值

如果該名稱已被設定，則返回true，否則返回false

?

public boolean startDiscovery ()

開始對遠程設備進行查找的進程

它通常牽涉到一個大概需時12秒的查詢掃描過程，緊跟著是一個對每個獲取到自身藍牙名稱的新設備的頁面掃描。

這是一個異步調用方法：該方法將馬上獲得返回值，注冊ACTION_DISCOVERY_STARTED and ACTION_DISCOVERY_FINISHED意圖準確地確定該探索是處于開始階段或者完成階段。注冊ACTION_FOUND以活動遠程藍牙設備 已找到的通知。

設備查找是一個重量級過程。當查找正在進行的時候，用戶不能嘗試對新的遠程藍牙設備進行連接，同時存在的連接將獲得有限制的帶寬以 及高等待時間。用戶可用cencelDiscovery()類來取消正在執(zhí)行的查找進程。發(fā)現(xiàn)的過程不會由活動來進行管理，但是它會作為一個系統(tǒng)服務來運 行，因此即使它不能直接請求這樣的一個查詢動作，也必需取消該搜索進程。

設備搜尋只尋找已經被連接的遠程設備。許多藍牙設備默認不會被搜尋到，并且需要進入到一個特殊的模式當中。

如果藍牙狀態(tài)不是STATE_ON，這個API將返回false。藍牙打開后，等待ACTION_STATE_CHANGED更新成STATE_ON。

需要BLUETOOTH_ADMIN權限。

返回值

成功返回true，錯誤返回false。

?

補充

???????? 文章精選

?????????????????? Android藍牙開發(fā)淺談

?????????????????? Android藍牙API之BluetoothAdapter類(1)

?????????????????? Android藍牙API之BluetoothAdapter類(2)

?????????????????? Ophone平臺藍牙編程基礎