Android教程網
  1. 首頁
  2. Android 技術
  3. Android 手機
  4. Android 系統教程
  5. Android 游戲
 Android教程網 >> Android技術 >> Android開發實例 >> Android 中文API (69) —— BluetoothAdapter

Android 中文API (69) —— BluetoothAdapter

編輯:Android開發實例

正文

  一、結構

 

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_MODEEXTRA_PREVIOUS_SCAN_MODE。這兩個附加域各自包含了新的和舊的掃描模式。

  需要BLUETOOTH權限

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

 

  String      ACTION_STATE_CHANGED   

  廣播活動:本來的藍牙適配器的狀態已經改變。

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

  它總是包含EXTRA_STATEEXTRA_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權限。

             返回值

 

 

  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。

  藍牙適配器的當前狀態

 

  1. 上一頁:
  2. 下一頁:
熱門文章
閱讀排行版
Copyright © Android教程網 All Rights Reserved