chrome.bluetoothSocket

說明

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

資訊清單

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

"bluetooth"

類型

AcceptError

列舉

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

"not_listening"
套接字未處於偵聽狀態。

AcceptErrorInfo

屬性

  • 錯誤

    AcceptError

    錯誤代碼，指出發生錯誤的情況。

  • errorMessage

    字串

    錯誤訊息。

  • socketId

    數字

    伺服器通訊端 ID。

AcceptInfo

屬性

  • clientSocketId

    數字

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

  • socketId

    數字

    伺服器通訊端 ID。

CreateInfo

屬性

  • socketId

    數字

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

ListenOptions

屬性

  • 待處理工作量

    號碼 選填

    套接字的監聽佇列長度。預設值取決於作業系統的主機子系統。

  • 頻道

    號碼 選填

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

  • psm

    號碼 選填

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

ReceiveError

列舉

「disconnected」
連線已中斷。

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

"not_connected"
未連結 Socket。

ReceiveErrorInfo

屬性

  • 錯誤

    ReceiveError

    錯誤代碼，指出發生錯誤的情況。

  • errorMessage

    字串

    錯誤訊息。

  • socketId

    數字

    這個屬性是 Socket ID。

ReceiveInfo

屬性

  • 資料

    ArrayBuffer

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

  • socketId

    數字

    這個屬性是 Socket ID。

SocketInfo

屬性

  • 地址

    string 選填

    如果底層 Socket 已連線，則包含已連線裝置的藍牙位址。

  • bufferSize

    號碼 選填

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

  • 已連線。

    布林值

    此標記用於指出 Socket 是否已連線至遠端對等端。

  • 名稱

    string 選填

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

  • 已暫停

    布林值

    標記可指出已連線的 Socket 是否阻止對等端傳送更多資料，或是監聽 Socket 上的連線要求是否透過 onAccept 事件調度，或是在監聽佇列待處理項目中排隊。請參閱 setPaused。預設值為「false」。

  • 永久

    布林值

    標記，指出在應用程式事件頁面卸載時，Socket 是否會保持開啟狀態 (請參閱 SocketProperties.persistent)。預設值為「false」。

  • socketId

    數字

    套接字 ID。

  • uuid

    string 選填

    如果底層 Socket 已連線，則包含與其連線的服務 UUID 相關資訊；如果底層 Socket 正在偵聽，則包含與其偵聽的服務 UUID 相關資訊。

SocketProperties

屬性

  • bufferSize

    號碼 選填

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

  • 名稱

    string 選填

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

  • 永久

    boolean 選填

    標記，指出在卸載應用程式的事件頁面時，是否要讓 Socket 保持開啟狀態 (請參閱「管理應用程式生命週期」)。預設值為 false.。載入應用程式時，如果先前使用 persistent=true 開啟的任何通訊埠，都可以透過 getSockets 擷取。

方法

close()

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

中斷並銷毀 Socket。每個建立的 Socket 都應在使用後關閉。函式一呼叫，這個 Socket ID 就會失效。不過，只有在呼叫回呼時，系統才會保證關閉 Socket。

參數

  • socketId

    數字

    套接字 ID。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

connect()

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

將 Socket 連線至遠端藍牙裝置。當 connect 作業順利完成時，系統會在從對等端接收資料時觸發 onReceive 事件。如果在執行階段接收封包時發生網路錯誤，系統會觸發 onReceiveError 事件，此時系統不會為此套接字觸發其他 onReceive 事件，直到呼叫 setPaused(false) 方法為止。

參數

  • socketId

    數字

    套接字 ID。

  • 地址

    字串

    藍牙裝置的位址。

  • uuid

    字串

    要連結的服務 UUID。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

create()

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

建立藍牙 Socket。

參數

  • 資源

    SocketProperties 選填

    套接字屬性 (選用)。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

      建立 Socket 的結果。

傳回

  • Promise<CreateInfo>

    Chrome 91 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

disconnect()

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

中斷 Socket。套接字 ID 仍有效。

參數

  • socketId

    數字

    套接字 ID。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

getInfo()

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

擷取指定 Socket 的狀態。

參數

  • socketId

    數字

    套接字 ID。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

      包含 Socket 資訊的物件。

傳回

  • Promise<SocketInfo>

    Chrome 91 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

getSockets()

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

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

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (sockets: SocketInfo[]) => void

傳回

  • Promise<SocketInfo[]>

    Chrome 91 以上版本

    承諾僅支援資訊清單 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 以上版本

    承諾僅支援資訊清單 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 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

send()

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

透過指定的藍牙 Socket 傳送資料。

參數

  • socketId

    數字

    套接字 ID。

  • 資料

    ArrayBuffer

    要傳送的資料。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (bytesSent: number) => void

    • bytesSent

      數字

      傳送的位元組數。

傳回

  • Promise<number>

    Chrome 91 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

setPaused()

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

啟用或停用已連線的 Socket 接收來自同儕的訊息，或監聽 Socket 接受新的連線。預設值為「false」。應用程式通常會暫停已連線的通訊 socket，以便節制對等端傳送的資料。當已連線的 Socket 處於暫停狀態時，系統不會觸發 onReceive 事件。當套接字已連線且已取消暫停時，系統會在收到訊息時再次觸發 onReceive 事件。當監聽式 Socket 處於暫停狀態時，系統會接受新連線，直到待處理連線數量達到上限為止，之後就會拒絕其他連線要求。只有在 Socket 取消暫停時，系統才會觸發 onAccept 事件。

參數

  • socketId

    數字

  • 已暫停

    布林值

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

update()

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

更新 Socket 屬性。

參數

  • socketId

    數字

    套接字 ID。

  • 要更新的房源屬性。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

活動

onAccept

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

在建立特定 Socket 的連線時觸發的事件。

參數

onAcceptError

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

當執行階段等待特定 Socket 上的新連線時發生網路錯誤，就會觸發此事件。這個事件觸發後，Socket 會設為 paused，且不會再為此 Socket 觸發 onAccept 事件。

參數

onReceive

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

在收到指定 Socket 的資料時觸發的事件。

參數

onReceiveError

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

執行階段等待通訊埠資料時發生網路錯誤時，系統會觸發這項事件。這個事件觸發後，Socket 會設為 paused，且不會再為此 Socket 觸發 onReceive 事件。

參數