說明
使用 chrome.bluetoothSocket
API 透過 RFCOMM 和 L2CAP 連線傳送資料至藍牙裝置。
資訊清單
類型
AcceptError
列舉
"system_error"
發生系統錯誤,可能無法復原連線。
"not_listening"
通訊端未監聽。
AcceptErrorInfo
屬性
-
錯誤
指出發生錯誤的錯誤代碼。
-
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
屬性
-
錯誤
指出發生錯誤的錯誤代碼。
-
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()
chrome.bluetoothSocket.close(
socketId: number,
callback?: function,
)
中斷連線並銷毀通訊端。使用之後,建立的每個通訊端都應該關閉。呼叫函式後,通訊端 ID 就會立即失效。但是,通訊端保證只有在叫用回呼時才會關閉。
參數
-
socketId
號碼
通訊端 ID。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 91 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
connect()
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()
chrome.bluetoothSocket.create(
properties?: SocketProperties,
callback?: function,
)
建立藍牙通訊端。
參數
-
資源
通訊端屬性 (選用)。
-
回呼
函式選用
callback
參數如下所示:(createInfo: CreateInfo) => void
-
createInfo
通訊端建立的結果。
-
傳回
-
Promise<CreateInfo>
Chrome 91 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
disconnect()
chrome.bluetoothSocket.disconnect(
socketId: number,
callback?: function,
)
拔除通訊端。通訊端 ID 仍然有效。
參數
-
socketId
號碼
通訊端 ID。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 91 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getInfo()
chrome.bluetoothSocket.getInfo(
socketId: number,
callback?: function,
)
擷取指定通訊端的狀態。
參數
-
socketId
號碼
通訊端 ID。
-
回呼
函式選用
callback
參數如下所示:(socketInfo: SocketInfo) => void
-
socketInfo
包含通訊端資訊的物件。
-
傳回
-
Promise<SocketInfo>
Chrome 91 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getSockets()
chrome.bluetoothSocket.getSockets(
callback?: function,
)
擷取應用程式擁有的通訊端清單。
參數
-
回呼
函式選用
callback
參數如下所示:(sockets: SocketInfo[]) => void
-
通訊端
-
傳回
-
Promise<SocketInfo[]>
Chrome 91 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
listenUsingL2cap()
chrome.bluetoothSocket.listenUsingL2cap(
socketId: number,
uuid: string,
options?: ListenOptions,
callback?: function,
)
監聽使用 L2CAP 通訊協定的連線。
參數
-
socketId
號碼
通訊端 ID。
-
uuid
字串
要監聽的服務 UUID。
-
選項
可選用的服務其他選項。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 91 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
listenUsingRfcomm()
chrome.bluetoothSocket.listenUsingRfcomm(
socketId: number,
uuid: string,
options?: ListenOptions,
callback?: function,
)
監聽使用 RFCOMM 通訊協定的連線。
參數
-
socketId
號碼
通訊端 ID。
-
uuid
字串
要監聽的服務 UUID。
-
選項
可選用的服務其他選項。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 91 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
send()
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()
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()
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,
)
為特定通訊端建立連線時引發的事件。
參數
-
回呼
功能
callback
參數如下所示:(info: AcceptInfo) => void
-
資訊
-
onAcceptError
chrome.bluetoothSocket.onAcceptError.addListener(
callback: function,
)
當執行階段等待指定通訊端上的新連線時發生網路錯誤時,就會引發事件。引發此事件後,通訊端會設為 paused
,不再針對此通訊端引發其他 onAccept
事件。
參數
-
回呼
功能
callback
參數如下所示:(info: AcceptErrorInfo) => void
onReceive
chrome.bluetoothSocket.onReceive.addListener(
callback: function,
)
系統收到特定通訊端的資料時引發的事件。
參數
-
回呼
功能
callback
參數如下所示:(info: ReceiveInfo) => void
-
資訊
-
onReceiveError
chrome.bluetoothSocket.onReceiveError.addListener(
callback: function,
)
當執行階段在通訊端等待通訊端的資料時發生網路錯誤時,就會引發事件。引發此事件後,通訊端會設為 paused
,不再針對此通訊端引發其他 onReceive
事件。
參數
-
回呼
功能
callback
參數如下所示:(info: ReceiveErrorInfo) => void