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

屬性

  • 待處理

    數字 選填

    通訊端的監聽佇列長度。預設值視作業系統的主機子系統而定。

  • 頻道

    數字 選填

    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

    數字 選填

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

  • 已連線。

    boolean

    此標記可註明通訊端是否已連線至遠端對等節點。

  • 名稱

    字串 選用

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

  • 已暫停

    boolean

    此標記會指出已連線通訊端是否阻止其對等傳送更多資料，或者是否透過 onAccept 事件傳送監聽通訊端的連線要求，或是是否排入監聽佇列中排入佇列。查看《setPaused》。預設值為「false」。

  • 永久

    boolean

    此標記表示當應用程式的事件頁面卸載時，通訊端是否保持開啟 (請參閱 SocketProperties.persistent)。預設值為「false」。

  • socketId

    號碼

    通訊端 ID。

  • uuid

    字串 選用

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

SocketProperties

屬性

  • bufferSize

    數字 選填

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

  • 名稱

    字串 選用

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

  • 永久

    布林值 (選用)

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

方法

close()

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

中斷連線並銷毀通訊端。使用之後，建立的每個通訊端都應該關閉。呼叫函式後，通訊端 ID 就會立即失效。但是，通訊端保證只有在叫用回呼時才會關閉。

參數

  • socketId

    號碼

    通訊端 ID。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 91 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

connect()

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

將通訊端連線到遠端藍牙裝置。connect 作業成功完成後，當從對等點接收資料時，就會引發 onReceive 事件。如果執行階段在接收封包時發生網路錯誤，系統會引發 onReceiveError 事件，此時到呼叫 setPaused(false) 方法之前，系統才會針對此通訊端發出其他 onReceive 事件。

參數

  • socketId

    號碼

    通訊端 ID。

  • 地址

    字串

    藍牙裝置的位址。

  • uuid

    字串

    要連線的服務 UUID。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 91 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

create()

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

建立藍牙通訊端。

參數

  • 資源

    SocketProperties 選用

    通訊端屬性 (選用)。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (createInfo: CreateInfo)=>void

    • createInfo

      CreateInfo

      通訊端建立的結果。

傳回

  • Promise<CreateInfo>

    Chrome 91 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

disconnect()

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

拔除通訊端。通訊端 ID 仍然有效。

參數

  • socketId

    號碼

    通訊端 ID。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 91 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

getInfo()

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

擷取指定通訊端的狀態。

參數

  • socketId

    號碼

    通訊端 ID。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (socketInfo: SocketInfo)=>void

    • socketInfo

      SocketInfo

      包含通訊端資訊的物件。

傳回

  • Promise<SocketInfo>

    Chrome 91 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

getSockets()

Promise 
chrome.bluetoothSocket.getSockets(
  callback?: function,
)

擷取應用程式擁有的通訊端清單。

參數

  • 回呼

    函式選用

    callback 參數如下所示： 

    (sockets: SocketInfo[])=>void

傳回

  • Promise<SocketInfo[]>

    Chrome 91 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

listenUsingL2cap()

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

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

參數

  • socketId

    號碼

    通訊端 ID。

  • uuid

    字串

    要監聽的服務 UUID。

  • 選項

    ListenOptions 選用

    可選用的服務其他選項。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 91 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

listenUsingRfcomm()

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

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

參數

  • socketId

    號碼

    通訊端 ID。

  • uuid

    字串

    要監聽的服務 UUID。

  • 選項

    ListenOptions 選用

    可選用的服務其他選項。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 91 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

send()

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

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

參數

  • socketId

    號碼

    通訊端 ID。

  • 資料或曾存取這類資料的人員

    ArrayBuffer

    要傳送的資料。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (bytesSent: number)=>void

    • bytesSent

      號碼

      傳送的位元組數。

傳回

  • Promise<number>

    Chrome 91 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

setPaused()

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

啟用或停用已連線的通訊端，以接收來自對等端的訊息，或接收端接收新連線的訊息。預設值為「false」。應用程式通常會使用已連線的通訊端，以限制其傳送的資料。連線通訊端暫停時，不會發出 onReceive 事件。當通訊端連線並取消暫停時，接收訊息時會再次引發 onReceive 事件。監聽通訊端暫停時，系統會接受新的連線，直到待處理工作恢復為止，其他連線要求都會遭拒。只有在通訊端取消暫停時，才會引發 onAccept 事件。

參數

  • socketId

    號碼

  • 已暫停

    boolean

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 91 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

update()

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

更新通訊端屬性。

參數

  • socketId

    號碼

    通訊端 ID。

  • 要更新的屬性。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 91 以上版本

    Promise 僅支援 Manifest V3 以上版本，其他平台就必須使用回呼。

活動

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 事件。

參數