chrome.bluetoothSocket

說明

使用 chrome.bluetoothSocket API，透過 RFCOMM 和 L2CAP 連線，將資料傳送至藍牙裝置及從藍牙裝置接收資料。

資訊清單

如要使用這項 API，必須在資訊清單中宣告下列鍵。

"bluetooth"

類型

AcceptError

列舉

「system_error」
系統發生錯誤，連線可能無法復原。

「not_listening」
插座未監聽。

AcceptErrorInfo

屬性

  • 錯誤

    AcceptError

    指出發生錯誤的錯誤代碼。

  • errorMessage

    字串

    錯誤訊息。

  • socketId

    數字

    伺服器通訊端 ID。

AcceptInfo

屬性

  • clientSocketId

    數字

    用戶端通訊端 ID，也就是新建立連線的通訊端 ID。這個通訊端 ID 只能與 chrome.bluetoothSocket 命名空間的函式搭配使用。請注意，用戶端通訊端一開始會暫停，應用程式必須明確取消暫停，才能開始接收資料。

  • socketId

    數字

    伺服器通訊端 ID。

CreateInfo

屬性

  • socketId

    數字

    新建立的通訊端 ID。請注意，透過這個 API 建立的通訊端 ID，與透過其他 API (例如 [sockets.tcp](../sockets_tcp/) API) 建立的通訊端 ID 不相容。

ListenOptions

屬性

  • backlog

    號碼 選填

    通訊端接聽佇列的長度。預設值取決於作業系統的主機子系統。

  • 頻道

    號碼 選填

    listenUsingRfcomm 使用的 RFCOMM 管道。如果指定了這個管道，則不得先前使用過，否則方法呼叫會失敗。如未指定，系統會自動分配未使用的頻道。

  • psm

    號碼 選填

    listenUsingL2cap 使用的 L2CAP PSM。如果指定，這個 PSM 先前不得使用，否則方法呼叫會失敗。如未指定，系統會自動分配未使用的 PSM。

ReceiveError

列舉

「已中斷連線」
連線已中斷。

「system_error」
系統發生錯誤，連線可能無法復原。

「not_connected」
插座尚未連線。

ReceiveErrorInfo

屬性

  • 錯誤

    ReceiveError

    指出發生錯誤的錯誤代碼。

  • errorMessage

    字串

    錯誤訊息。

  • socketId

    數字

    插座 ID。

ReceiveInfo

屬性

  • 資料

    ArrayBuffer

    收到的資料，大小上限為 bufferSize。

  • socketId

    數字

    插座 ID。

SocketInfo

屬性

  • 地址

    字串 選填

    如果基礎通訊端已連線，則包含所連線裝置的藍牙位址。

  • bufferSize

    號碼 選填

    用來接收資料的緩衝區大小。如果未明確指定緩衝區大小，系統就不會提供值。

  • 已連線。

    布林值

    此標記用於註明通訊端是否已連線至遠端對等互連裝置。

  • 名稱

    字串 選填

    與通訊端相關聯的應用程式定義字串。

  • 已暫停

    布林值

    這個旗標表示連線的通訊端是否會阻止對等互連傳送更多資料，或是監聽通訊端上的連線要求是否會透過 onAccept 事件分派，或在監聽佇列待辦事項中排隊。詳情請參閱 setPaused。預設值為「false」。

  • 永久

    布林值

    這個旗標指出卸載應用程式的事件頁面時，插座是否保持開啟狀態 (請參閱 SocketProperties.persistent)。預設值為「false」。

  • socketId

    數字

    插座 ID。

  • uuid

    字串 選填

    如果基礎通訊端已連線，則包含所連線服務 UUID 的相關資訊；否則，如果基礎通訊端正在接聽，則包含正在接聽的服務 UUID 相關資訊。

SocketProperties

屬性

  • bufferSize

    號碼 選填

    用來接收資料的緩衝區大小。預設值為 4096。

  • 名稱

    字串 選填

    與通訊端相關聯的應用程式定義字串。

  • 永久

    布林值 選填

    這個標記表示應用程式的事件頁面卸載時，是否會讓通訊端保持開啟狀態 (請參閱「管理應用程式生命週期」)。預設值為 false.。載入應用程式時，先前以 persistent=true 開啟的任何通訊端都可以使用 getSockets 擷取。

方法

close()

Promise 
chrome.bluetoothSocket.close(
  socketId: number,
  callback?: function,
): Promise<void>

中斷連線並終結通訊端。建立的每個通訊端都應在使用後關閉。只要呼叫函式，插槽 ID 就會失效。不過，只有在叫用回呼時，才能保證插槽已關閉。

參數

  • socketId

    數字

    插座 ID。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

connect()

Promise 
chrome.bluetoothSocket.connect(
  socketId: number,
  address: string,
  uuid: string,
  callback?: function,
): Promise<void>

將插座連線至遠端藍牙裝置。connect 作業順利完成後，系統會在收到對等互連裝置的資料時引發 onReceive 事件。如果執行階段接收封包時發生網路錯誤，系統會引發 onReceiveError 事件，此時，除非呼叫 setPaused(false) 方法，否則這個通訊端不會再引發 onReceive 事件。

參數

  • socketId

    數字

    插座 ID。

  • 地址

    字串

    藍牙裝置的位址。

  • uuid

    字串

    要連線的服務 UUID。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

create()

Promise 
chrome.bluetoothSocket.create(
  properties?: SocketProperties,
  callback?: function,
): Promise<CreateInfo>

建立藍牙通訊端。

參數

  • 資源

    SocketProperties optional

    插座屬性 (選用)。

  • callback

    函式 選用

    callback 參數如下： 

    (createInfo: CreateInfo) => void

傳回

  • Promise<CreateInfo>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

disconnect()

Promise 
chrome.bluetoothSocket.disconnect(
  socketId: number,
  callback?: function,
): Promise<void>

中斷通訊端連線。插座 ID 仍有效。

參數

  • socketId

    數字

    插座 ID。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getInfo()

Promise 
chrome.bluetoothSocket.getInfo(
  socketId: number,
  callback?: function,
): Promise<SocketInfo>

擷取指定插座的狀態。

參數

  • socketId

    數字

    插座 ID。

  • callback

    函式 選用

    callback 參數如下： 

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

      包含通訊端資訊的物件。

傳回

  • Promise<SocketInfo>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getSockets()

Promise 
chrome.bluetoothSocket.getSockets(
  callback?: function,
): Promise<SocketInfo[]>

擷取應用程式目前開啟的通訊端清單。

參數

  • callback

    函式 選用

    callback 參數如下： 

    (sockets: SocketInfo[]) => void

傳回

  • Promise<SocketInfo[]>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

listenUsingL2cap()

Promise 
chrome.bluetoothSocket.listenUsingL2cap(
  socketId: number,
  uuid: string,
  options?: ListenOptions,
  callback?: function,
): Promise<void>

使用 L2CAP 通訊協定監聽連線。

參數

  • socketId

    數字

    插座 ID。

  • uuid

    字串

    要監聽的服務 UUID。

  • 選項

    ListenOptions optional

    服務的選用其他選項。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

listenUsingRfcomm()

Promise 
chrome.bluetoothSocket.listenUsingRfcomm(
  socketId: number,
  uuid: string,
  options?: ListenOptions,
  callback?: function,
): Promise<void>

使用 RFCOMM 通訊協定監聽連線。

參數

  • socketId

    數字

    插座 ID。

  • uuid

    字串

    要監聽的服務 UUID。

  • 選項

    ListenOptions optional

    服務的選用其他選項。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

send()

Promise 
chrome.bluetoothSocket.send(
  socketId: number,
  data: ArrayBuffer,
  callback?: function,
): Promise<number>

傳送指定藍牙通訊端的資料。

參數

  • socketId

    數字

    插座 ID。

  • 資料

    ArrayBuffer

    要傳送的資料。

  • callback

    函式 選用

    callback 參數如下： 

    (bytesSent: number) => void

    • bytesSent

      數字

      傳送的位元組數。

傳回

  • Promise<number>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

setPaused()

Promise 
chrome.bluetoothSocket.setPaused(
  socketId: number,
  paused: boolean,
  callback?: function,
): Promise<void>

啟用或停用連線的通訊端，使其無法接收來自對等互連的訊息，或是停用接聽通訊端，使其無法接受新連線。預設值為「false」。應用程式通常會暫停已連線的通訊端，藉此限制對等互連傳送的資料。連線的通訊端暫停時，不會引發任何 onReceive 事件。連線並取消暫停 Socket 後，系統會在收到訊息時再次引發 onReceive 事件。接聽通訊端暫停時，系統會接受新連線，直到後續記錄已滿，才會拒絕其他連線要求。只有在取消暫停通訊端時，才會引發 onAccept 事件。

參數

  • socketId

    數字

  • 已暫停

    布林值

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

update()

Promise 
chrome.bluetoothSocket.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
): Promise<void>

更新通訊端屬性。

參數

  • socketId

    數字

    插座 ID。

  • 要更新的屬性。

  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

事件

onAccept

chrome.bluetoothSocket.onAccept.addListener(
  callback: function,
)

當特定通訊端已建立連線時，系統會引發事件。

參數

onAcceptError

chrome.bluetoothSocket.onAcceptError.addListener(
  callback: function,
)

當執行階段等待指定通訊端上的新連線時發生網路錯誤，就會引發這個事件。一旦引發這個事件，插槽就會設為 paused，且不會再為這個插槽引發 onAccept 事件。

參數

onReceive

chrome.bluetoothSocket.onReceive.addListener(
  callback: function,
)

當特定通訊端收到資料時，系統會引發事件。

參數

onReceiveError

chrome.bluetoothSocket.onReceiveError.addListener(
  callback: function,
)

執行階段等待插座上的資料時發生網路錯誤，就會引發這個事件。一旦引發這個事件，插槽就會設為 paused，且不會再為這個插槽引發 onReceive 事件。

參數