Android 中文API （69） —— BluetoothAdapter[藍牙]

正文

　　一、結構

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)方法來監聽新來的連接配接請求。

　　參見

　　三、常量

　　　　String      ACTION_DISCOVERY_FINISHED   

　　廣播事件：本地藍牙擴充卡已經完成裝置的搜尋過程。

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

　　String      ACTION_DISCOVERY_STARTED    

　　廣播事件：本地藍牙擴充卡已經開始對遠端裝置的搜尋過程。

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

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

　　String      ACTION_LOCAL_NAME_CHANGED      

　　廣播活動：本地藍牙擴充卡已經更改了它的藍牙名稱。

　　該名稱對遠端藍牙裝置是可見的。

　　它總是包含了一個帶有名稱的EXTRA_LOCAL_NAME附加域。

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

　　String      ACTION_REQUEST_DISCOVERABLE      

　　Activity活動：顯示一個請求被搜尋模式的系統活動。如果藍牙子產品目前未打開，該活動也将請求使用者打開藍牙子產品。

　　從隐私安全考慮，Android不會将被搜尋模式設定為預設狀态。

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

　　String      ACTION_REQUEST_ENABLE

　　Activity活動：顯示一個允許使用者打開藍牙子產品的系統活動。

　　當藍牙子產品完成打開工作，或者當使用者決定不打開藍牙子產品時，系統活動将傳回該值。

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

　　String      ACTION_SCAN_MODE_CHANGED        

　　廣播活動：指明藍牙掃描子產品或者本地擴充卡已經發生變化

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

　　String      ACTION_STATE_CHANGED   

　　廣播活動：本來的藍牙擴充卡的狀态已經改變。

　　例如：藍牙子產品已經被打開或者關閉。

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

　　int  ERROR   

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

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

　　常量值: -2147483648 (0x80000000)

　　String      EXTRA_DISCOVERABLE_DURATION     

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

　　String      EXTRA_LOCAL_NAME   

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

　　String      EXTRA_PREVIOUS_SCAN_MODE  

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

　　String      EXTRA_PREVIOUS_STATE      

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

　　String      EXTRA_SCAN_MODE     

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

　　String      EXTRA_STATE         

　　常量值: "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    

　　常量值: 11 (0x0000000b)

　　四、公共方法

　　public boolean cancelDiscovery ()

　　取消目前的裝置發現查找程序

　　因為對藍牙擴充卡而言，查找是一個重量級的過程，是以這個方法必須在嘗試連接配接到遠端裝置前使用用connect()方法進行調用。發現的過程不會由活動來進行管理，但是它會作為一個系統服務來運作，是以即使它不能直接請求這樣的一個查詢動作，也必需取消該搜尋程序。

　　傳回值

　　成功則傳回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，那麼系統已經有一個保護藍牙擴充卡被關閉的問題—比如該擴充卡已經被關閉了。

                 傳回值

　　如果藍牙擴充卡的停止程序已經開啟則傳回true，如果産生錯誤則傳回false。

　　public boolean enable ()

           打開本地藍牙擴充卡—不能在沒有明确打開藍牙的使用者動作中使用。

　　該方法将為基礎的藍牙硬體供電，并且啟動所有的藍牙系統服務。

　　沒有使用者的直接同意，藍牙永遠不能被禁止。如果使用者為了建立無線連接配接而打開了藍牙子產品，則其需要ACTION_REQUEST_ENABLE值，該值将提出 一個請求使用者允許以打開藍牙子產品的會話。這個enable()值隻提供了一個應用，該應用包含了一個改變系統設定的使用者界面（例如“電源控制”應用）。

　　這是一個異步調用方法：該方法将馬上獲得傳回值，使用者要通過監聽ACTION_STATE_CHANGED值來擷取随後的擴充卡狀态改變的通知。如果該調用 傳回true值，則該擴充卡狀态會立刻從STATE_OFF轉向STATE_TURNING_ON，稍後則會轉為STATE_OFF或者 STATE_ON。如果該調用傳回false，那麼說明系統已經有一個保護藍牙擴充卡被打開的問題—比如飛行模式，或者該擴充卡已經被打開。

　　傳回值    

　　如果藍牙擴充卡的打開程序已經開啟則傳回true，如果産生錯誤則傳回false。

　　public String getAddress ()

　　傳回本地藍牙擴充卡的硬體位址

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

　　字元串形式的藍牙子產品位址

　　public Set<BluetoothDevice> getBondedDevices ()

　　傳回已經比對到本地擴充卡的BluetoothDevice類的對象集合

　　未被修改的BluetoothDevice類的對象集合，如果有錯誤則傳回null。

　　public static synchronized BluetoothAdapter getDefaultAdapter ()

　　擷取對預設本地藍牙擴充卡的的操作權限。

　　目前Andoird隻支援一個藍牙擴充卡，但是API可以被擴充為支援多個擴充卡。該方法總是傳回預設的擴充卡。

　　傳回預設的本地擴充卡，如果藍牙擴充卡在該硬體平台上不能被支援，則傳回null。

　　public String getName ()

　　擷取本地藍牙擴充卡的藍牙名稱

　　這個名稱對于外界藍牙裝置而言是可見的。

　　該藍牙擴充卡名稱，如果有錯誤則傳回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.

      　　傳回值

　　掃描模式

　　public int getState ()

　　擷取本地藍牙擴充卡的目前狀态

　　可能值有 STATE_OFF, STATE_TURNING_ON, STATE_ON, STATE_TURNING_OFF. 

需要BLUETOOTH類

           　　傳回值

　　public boolean isDiscovering ()

　　如果目前藍牙擴充卡正處于裝置發現查找程序中，則傳回真值

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

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

　　如果正在查找，則傳回true

　　public boolean isEnabled ()

　　如果藍牙正處于打開狀态并可用，則傳回真值

　　與getBluetoothState()==STATE_ON 等價

　　如果本地擴充卡已經打開，則傳回true

　　public BluetoothServerSocket listenUsingRfcommWithServiceRecord (String name, UUID uuid)

　　建立一個正在監聽的安全的帶有服務記錄的無線射頻通信（RFCOMM）藍牙端口。

　　一個對該端口進行連接配接的遠端裝置将被認證，對該端口的通訊将被加密。

　　該系統配置設定一個未被使用的無線射頻通信通道來進行監聽。

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

　　name       SDP記錄下的伺服器名

　　uuid         SDP記錄下的UUID

　　一個正在監聽的無線射頻通信藍牙服務端口

　　IOException    産生錯誤，比如藍牙裝置不可用，或者許可無效，或者通道被占用。

　　public boolean setName (String name)

　　設定藍牙或者本地藍牙擴充卡的昵稱.

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

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

　　name       一個合法的藍牙名稱

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

　　public boolean startDiscovery ()

　　開始對遠端裝置進行查找的程序

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

　　裝置查找是一個重量級過程。當查找正在進行的時候，使用者不能嘗試對新的遠端藍牙裝置進行連接配接，同時存在的連接配接将獲得有限制的帶寬以 及高等待時間。使用者可用cencelDiscovery()類來取消正在執行的查找程序。發現的過程不會由活動來進行管理，但是它會作為一個系統服務來運 行，是以即使它不能直接請求這樣的一個查詢動作，也必需取消該搜尋程序。

　　裝置搜尋隻尋找已經被連接配接的遠端裝置。許多藍牙裝置預設不會被搜尋到，并且需要進入到一個特殊的模式當中。

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

　　藍牙擴充卡的目前狀态

本文轉自over140 51CTO部落格，原文連結：http://blog.51cto.com/over140/582526，如需轉載請自行聯系原作者